|
| 1 | +import Tabs from '@theme/Tabs'; |
| 2 | +import TabItem from '@theme/TabItem'; |
| 3 | + |
| 4 | +# Quickstart |
| 5 | + |
| 6 | +In this tutorial we will build a simple Telegram bot that will run inside ROFL. |
| 7 | +Along the way we will meet one of the most powerful ROFL features—how to safely |
| 8 | +store your bot's Telegram API token inside a built-in ROFL key-store protected |
| 9 | +by the Trusted Execution Environment and the Oasis blockchain! |
| 10 | + |
| 11 | +## Python Telegram Bot |
| 12 | + |
| 13 | +We will use a very simple [python-telegram-bot] wrapper. As a good python |
| 14 | +citizen create a new folder for your project. Then, set up a python virtual |
| 15 | +environment and properly install the `python-telegram-bot` dependency: |
| 16 | + |
| 17 | +```shell |
| 18 | +python -m venv my_env |
| 19 | +source my_env/bin/activate |
| 20 | +echo python-telegram-bot > requirements.txt |
| 21 | +pip install -r requirements.txt |
| 22 | +``` |
| 23 | + |
| 24 | +Create a file called `bot.py` and paste the following bot logic that greets us |
| 25 | +back after greeting it with the `/hello` command: |
| 26 | + |
| 27 | +```python title="bot.py" |
| 28 | +import os |
| 29 | +from telegram import Update |
| 30 | +from telegram.ext import ApplicationBuilder, CommandHandler, ContextTypes |
| 31 | + |
| 32 | + |
| 33 | +async def hello(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None: |
| 34 | + await update.message.reply_text(f'Hello {update.effective_user.first_name}') |
| 35 | + |
| 36 | + |
| 37 | +app = ApplicationBuilder().token(os.getenv["TOKEN"]).build() |
| 38 | + |
| 39 | +app.add_handler(CommandHandler("hello", hello)) |
| 40 | + |
| 41 | +app.run_polling() |
| 42 | +``` |
| 43 | + |
| 44 | +Next, we'll need to generate a Telegram API token for our bot. Search for |
| 45 | +`@BotFather` in your Telegram app and start a chat with the `/newbot` command. |
| 46 | +Then, you'll need to input the name and a username of your bot. Finally, |
| 47 | +`@BotFather` will provide you a token that resembles something like |
| 48 | +`0123456789:AAGax-vgGmQsRiwf4WIQI4xq8MMf4WaQI5x`. |
| 49 | + |
| 50 | +As you may have noticed our bot above will read its Telegram API token from the |
| 51 | +`TOKEN` *environment variable*. Since we'll use this variable throughout the |
| 52 | +tutorial, let's export it for our session and then we can run our bot: |
| 53 | + |
| 54 | +```shell |
| 55 | +export TOKEN="0123456789:AAGax-vgGmQsRiwf4WIQI4xq8MMf4WaQI5x" |
| 56 | +python bot.py |
| 57 | +``` |
| 58 | + |
| 59 | +The bot should be up and running now, so you can search for its username in your |
| 60 | +Telegram app and send it a `/hello` message: |
| 61 | + |
| 62 | + |
| 63 | + |
| 64 | +[python-telegram-bot]: https://pypi.org/project/python-telegram-bot/ |
| 65 | + |
| 66 | +## Dockerize the Bot |
| 67 | + |
| 68 | +Web services are best maintained if they are run in a controlled environment |
| 69 | +also known as *a container*. This includes the exact version of the operating |
| 70 | +system, both system and user libraries, and your carefully configured service. |
| 71 | +The image of the container is uploaded to an *OCI file server* (e.g. docker.io, |
| 72 | +ghcr.io) from where the server hosting your bot downloads it. |
| 73 | + |
| 74 | +In our example we will use Docker to build a python-based image and add our |
| 75 | +Telegram bot on top of it. Go ahead and [install Docker][docker] on your |
| 76 | +system. Then, inside our project folder create a file called `Dockerfile` with |
| 77 | +the following content: |
| 78 | + |
| 79 | +```dockerfile title="Dockerfile" |
| 80 | +FROM python:alpine3.17 |
| 81 | + |
| 82 | +WORKDIR /bot |
| 83 | +COPY ./bot.py ./requirements.txt /bot |
| 84 | +RUN pip install -r requirements.txt |
| 85 | + |
| 86 | +ENTRYPOINT ["python", "bot.py"] |
| 87 | +``` |
| 88 | + |
| 89 | +Next, create a `compose.yaml` file which orchestrates our container: |
| 90 | + |
| 91 | +```yaml title="compose.yaml" |
| 92 | +services: |
| 93 | + python-telegram-bot: |
| 94 | + build: . |
| 95 | + image: "ghcr.io/oasisprotocol/demo-rofl-tgbot" |
| 96 | + platform: linux/amd64 |
| 97 | + environment: |
| 98 | + - TOKEN=${TOKEN} |
| 99 | +``` |
| 100 | +
|
| 101 | +Let's build the docker image now and test it locally with the `docker compose` |
| 102 | +command: |
| 103 | + |
| 104 | +```shell |
| 105 | +docker compose build |
| 106 | +docker compose up |
| 107 | +``` |
| 108 | + |
| 109 | +If you launch your Telegram app and send a `/hello` message to our bot, you |
| 110 | +should get the same response back as you did previously—this time running inside |
| 111 | +a Docker container. |
| 112 | + |
| 113 | +:::tip Adjust `image:` field to fit your needs |
| 114 | + |
| 115 | +The `image:` field(s) in `compose.yaml` above must point to a publicly |
| 116 | +accessible OCI file server where your image will be downloaded from for |
| 117 | +execution. In our example, we didn't push a new image, but just used |
| 118 | +`ghcr.io/oasisprotocol/demo-rofl-tgbot` prepared by the Oasis team and combined |
| 119 | +with our `TOKEN` secret. |
| 120 | + |
| 121 | +If you wish to build and deploy your own image, replace the `image:` field with |
| 122 | +a fully qualified domain of the OCI server you use followed by your username, |
| 123 | +for example: |
| 124 | + |
| 125 | +- `docker.io/your_username/demo-rofl-tgbot` |
| 126 | +- `ghcr.io/your_username/demo-rofl-tgbot` |
| 127 | + |
| 128 | +After building and tagging the image with `docker compose build`, run |
| 129 | +`docker compose push` to upload it. |
| 130 | + |
| 131 | +::: |
| 132 | + |
| 133 | +[docker]: https://www.docker.com/ |
| 134 | + |
| 135 | +## ROFLize the Bot |
| 136 | + |
| 137 | +The final step is to prepare our Docker container for execution inside the |
| 138 | +*Trusted Execution Environment (TEE)*. First, download the latest release of the |
| 139 | +Oasis CLI [here][oasis-cli-dl] and install it on your computer. |
| 140 | + |
| 141 | +If you don't have an existing account on Oasis Sapphre Testnet chain, you will |
| 142 | +need to create or import it with the [`oasis wallet create`] or [`oasis wallet |
| 143 | +import`] commands respectively. Then, fund the acount with ~110 TEST tokens: 100 |
| 144 | +tokens for the ROFL registration escrow and another 10 TEST or so for paying |
| 145 | +different kinds of gas fees. To fund the account with TEST tokens, visit the |
| 146 | +official [Oasis Testnet faucet] or reach out to us on the |
| 147 | +[`#dev-central` channel on Discord][discord]. |
| 148 | + |
| 149 | +[`oasis wallet create`]: https://github.com/oasisprotocol/cli/blob/master/docs/wallet.md#create |
| 150 | +[`oasis wallet import`]: https://github.com/oasisprotocol/cli/blob/master/docs/wallet.md#import |
| 151 | + |
| 152 | + |
| 153 | +[Oasis Testnet faucet]: https://faucet.testnet.oasis.io |
| 154 | +[discord]: https://oasis.io/discord |
| 155 | + |
| 156 | +Next, inside our project folder, run the following command to generate the |
| 157 | +initial `rofl.yaml` manifest file and to register a new ROFL app on Sapphire |
| 158 | +Testnet: |
| 159 | + |
| 160 | +```shell |
| 161 | +oasis rofl init |
| 162 | +oasis rofl create |
| 163 | +``` |
| 164 | + |
| 165 | +Now, we will build the *ROFL bundle* .orc. This file packs `compose.yaml`, |
| 166 | +specific operating system components and the hash of a trusted block on the |
| 167 | +Sapphire chain. All these pieces are needed to safely execute our bot |
| 168 | +inside TEE. |
| 169 | + |
| 170 | +<Tabs> |
| 171 | + <TabItem value="Native Linux"> |
| 172 | + ```shell |
| 173 | + oasis rofl build |
| 174 | + ``` |
| 175 | + </TabItem> |
| 176 | + <TabItem value="Docker (Windows, Mac, Linux)"> |
| 177 | + ```shell |
| 178 | + docker run --platform linux/amd64 --volume .:/src -it ghcr.io/oasisprotocol/rofl-dev:main oasis rofl build |
| 179 | + ``` |
| 180 | + </TabItem> |
| 181 | +</Tabs> |
| 182 | + |
| 183 | +Do you recall the `TOKEN` environment variable we exported above? Now, we will |
| 184 | +encrypt it and safely store it on-chain, so that it will be fed to our bot |
| 185 | +container once it's started on one of the TEE provider's nodes: |
| 186 | + |
| 187 | +```shell |
| 188 | +echo -n "$TOKEN" | oasis rofl secret set TOKEN - |
| 189 | +``` |
| 190 | + |
| 191 | +To submit this secret and the signatures (*enclave IDs*) of our .orc bundle |
| 192 | +components on-chain run: |
| 193 | + |
| 194 | +```shell |
| 195 | +oasis rofl update |
| 196 | +``` |
| 197 | + |
| 198 | +Finally, we deploy our ROFL app to a Testnet node instance offered by one of the |
| 199 | +ROFL providers: |
| 200 | + |
| 201 | +```shell |
| 202 | +oasis rofl deploy |
| 203 | +``` |
| 204 | + |
| 205 | +Congratulations, you have just deployed your first ROFL app! 🎉 |
| 206 | + |
| 207 | +Go ahead and test it by sending the `/hello` message in the Telegram app. You |
| 208 | +can also check out your ROFL app on the [Oasis Explorer]: |
| 209 | + |
| 210 | + |
| 211 | + |
| 212 | +:::info Example: demo-rofl-tgbot |
| 213 | + |
| 214 | +You can fetch a finished project of this tutorial from GitHub |
| 215 | +[here][demo-rofl-tgbot]. |
| 216 | + |
| 217 | +::: |
| 218 | + |
| 219 | +The tutorial above was just a Quickstart demonstrating how simple it is to run |
| 220 | +your app inside a Trusted Execution Environment with Oasis ROFL. Read the |
| 221 | +following chapters to take a deep dive into unique confidential features enabled |
| 222 | +by the Oasis platform. |
| 223 | + |
| 224 | +[oasis-cli-dl]: https://github.com/oasisprotocol/cli/releases |
| 225 | +[demo-rofl-tgbot]: https://github.com/oasisprotocol/demo-rofl-tgbot |
| 226 | +[Oasis Explorer]: https://pr-1777.oasis-explorer.pages.dev/testnet/sapphire/rofl/app/rofl1qpjsc3qplf2szw7w3rpzrpq5rqvzv4q5x5j23msu |
0 commit comments