diff --git a/.github/workflows/rofl-dev-image.yml b/.github/workflows/rofl-dev-image.yml new file mode 100644 index 0000000000..a61342bb90 --- /dev/null +++ b/.github/workflows/rofl-dev-image.yml @@ -0,0 +1,83 @@ +# NOTE: This name appears in GitHub's Checks API and in workflow's status badge. +name: rofl-dev-image + +on: + push: + # XXX: ideally on main branches we would build the image only if there are changes in the + # 'docker/' directory (as we do in pull_requests). However, this doesn't work when pushing a new + # 'stable/*' branch - the build on a new branch does not trigger unless there are changes + # compared to main on the filtered path. + # If this is ever fixed, or per branch filters are possible, bring back the path filter to only + # build the image when there are changes within 'docker/' directory. + branches: + - main + - stable/* + # Or when a pull request event occurs for a pull request against one of the matched branches and at least + # one modified file matches the configured paths. + # + # NOTE: We use this to be able to easily test Docker image changes. + pull_request: + branches: + - main + - stable/* + paths: + - docker/rofl-dev/** + # Or every day at 04:00 UTC (for the default/main branch). + schedule: + - cron: "0 4 * * *" + +# Cancel in-progress jobs on same branch. +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + + build-rofl-dev: + # NOTE: This name appears in GitHub's Checks API. + name: build-rofl-dev + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + # Check out pull request's HEAD commit instead of the merge commit. + ref: ${{ github.event.pull_request.head.sha }} + + - name: Determine tag name + id: determine-tag + uses: ./.github/actions/determine-tag + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Login to ghcr.io + uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: "Rebuild oasisprotocol/rofl-dev:${{ steps.determine-tag.outputs.tag }}" + uses: docker/build-push-action@v5 + with: + context: docker/rofl-dev + file: docker/rofl-dev/Dockerfile + tags: ghcr.io/oasisprotocol/rofl-dev:${{ steps.determine-tag.outputs.tag }} + pull: true + push: true + labels: | + org.opencontainers.image.source=${{ github.event.repository.html_url }} + org.opencontainers.image.created=${{ steps.determine-tag.outputs.created }} + org.opencontainers.image.revision=${{ github.sha }} + + - name: Prune old ghcr.io/oasisprotocol/rofl-dev images + uses: vlaurin/action-ghcr-prune@v0.6.0 + with: + token: ${{ secrets.GITHUB_TOKEN }} + organization: oasisprotocol + container: rofl-dev + keep-younger-than: 7 # days + keep-last: 2 + prune-untagged: true + prune-tags-regexes: ^pr- diff --git a/docker/rofl-dev/Dockerfile b/docker/rofl-dev/Dockerfile new file mode 100644 index 0000000000..54b7d6bdef --- /dev/null +++ b/docker/rofl-dev/Dockerfile @@ -0,0 +1,14 @@ +FROM ghcr.io/oasisprotocol/oasis-core-dev:stable-24.3.x AS oasis-core-dev + +ARG OASIS_CLI_VERSION=0.10.3 + +ENV RUSTFLAGS="-C target-feature=+aes,+ssse3" +ENV RUSTDOCFLAGS="-C target-feature=+aes,+ssse3" + +RUN curl -L -o /tmp/cli.tar.gz "https://github.com/oasisprotocol/cli/releases/download/v${OASIS_CLI_VERSION}/oasis_cli_${OASIS_CLI_VERSION}_linux_amd64.tar.gz" && \ + tar -C /usr/bin -xf /tmp/cli.tar.gz --strip-components 1 "oasis_cli_${OASIS_CLI_VERSION}_linux_amd64/oasis" && \ + rm /tmp/cli.tar.gz + +VOLUME /src + +WORKDIR /src diff --git a/docs/rofl/app.md b/docs/rofl/app.mdx similarity index 89% rename from docs/rofl/app.md rename to docs/rofl/app.mdx index 18a4b2fc8a..deadac61c9 100644 --- a/docs/rofl/app.md +++ b/docs/rofl/app.mdx @@ -1,3 +1,6 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # Application This chapter will show you how to quickly create, build and test a minimal @@ -71,6 +74,14 @@ configure Cargo to always build with specific target CPU platform features (namely AES-NI and SSE3) by creating a `.cargo/config.toml` file with the following content: +:::info + +You do not need this additional configuration if you're building with the +[`rofl-dev`][rofl-dev] container, since that already has the relevant environment +variables set appropriately. + +::: + ```toml title=".cargo/config.toml" [build] rustflags = ["-C", "target-feature=+aes,+ssse3"] @@ -132,11 +143,23 @@ The simplest way to test and debug your ROFL is with a local stack. ``` 2. Navigate to `examples/runtime-sdk/rofl-oracle` and compile -ROFL in the _unsafe_ mode: - - ```shell - oasis rofl build sgx --mode unsafe - ``` + ROFL in the _unsafe_ mode. If you're using the [`rofl-dev`][rofl-dev] + docker image (e.g. because you're developing on macOS), you can run the + container, build the app, and stop the container in just a single + command. + + + + ```shell + oasis rofl build sgx --mode unsafe + ``` + + + ```shell + docker run --platform linux/amd64 --volume .:/src -it ghcr.io/oasisprotocol/rofl-dev oasis rofl build sgx --mode unsafe + ``` + + 3. Spin up the Sapphire Localnet docker container and mount your `rofl-oracle` folder to `/rofls` inside the docker image: @@ -154,6 +177,8 @@ information. [localnet]: https://github.com/oasisprotocol/docs/blob/main/docs/dapp/tools/localnet.mdx +[rofl-dev]: https://github.com/oasisprotocol/oasis-sdk/pkgs/container/rofl-dev + ``` sapphire-localnet 2024-09-19-git2332dba (oasis-core: 24.2, sapphire-paratime: 0.8.2, oasis-web3-gateway: 5.1.0) diff --git a/docs/rofl/deployment.md b/docs/rofl/deployment.md index c254ab6f79..573f8c5386 100644 --- a/docs/rofl/deployment.md +++ b/docs/rofl/deployment.md @@ -20,7 +20,7 @@ This way, your ROFL client will sync more quickly and not want to start on any other network or ParaTime. Read the [Consensus Trust Root] chapter to learn more about obtaining a correct block for the root of trust. -[`src/main.rs`]: app.md#app-definition +[`src/main.rs`]: app.mdx#app-definition [Consensus Trust Root]: trust-root.md ## Register the App diff --git a/docs/rofl/prerequisites.md b/docs/rofl/prerequisites.md index c910dcdb89..7fe9ab4905 100644 --- a/docs/rofl/prerequisites.md +++ b/docs/rofl/prerequisites.md @@ -10,7 +10,28 @@ steps you will be able to start building your first ROFL app! If you already have everything set up, feel free to skip to the [next chapter]. -[next chapter]: app.md +[next chapter]: app.mdx + +:::info + +Docker images are available to help you set up a development +environment. If you don't want to install everything locally (or **in +particular if you use macOS** as your development system), you can use +the `ghcr.io/oasisprotocol/rofl-dev` image, which contains all the tools +needed to compile a ROFL app. + +To use it, bind the directory with your app source to the container's +`/src` directory with a command like the following, then continue with +the next section of this guide: + +```bash +docker run --platform linux/amd64 --volume ./rofl-oracle:/src -it ghcr.io/oasisprotocol/rofl-dev +``` + +Note that on macOS you **must** use the `--platform linux/amd64` +parameter, no matter which processor your computer has. + +::: ## Environment Setup @@ -77,20 +98,18 @@ nightly-2022-08-22-x86_64-unknown-linux-gnu (overridden by '/code/rust-toolchain rustc 1.65.0-nightly (c0941dfb5 2022-08-21) ``` -For testing ROFL binaries on Sapphire Localnet, the binaries should be compiled -for [MUSL C standard library]. You will need to add the following target to your -rust environment: +Make sure you have the correct target for rust to compile for: ```shell -rustup target add x86_64-unknown-linux-musl +rustup target add x86_64-unknown-linux-gnu ``` -Additionally, you will need the MUSL wrapper for gcc, the multilib package and -clang for compiling the `mbedtls-sys-auto` dependency. On Ubuntu/Debian systems, -you can install those by running: +In addition, you will need gcc's multilib support package, the protobuf +compiler, clang, and cmake for compiling the `mbedtls-sys-auto` +dependency. On Ubuntu/Debian systems, you can install those by running: ```shell -sudo apt install musl-tools gcc-multilib clang +sudo apt install gcc-multilib clang protobuf-compiler cmake pkg-config ``` @@ -100,7 +119,6 @@ sudo apt install musl-tools gcc-multilib clang [Rust]: https://www.rust-lang.org/ [`rust-toolchain.toml`]: https://github.com/oasisprotocol/oasis-sdk/tree/main/rust-toolchain.toml [rust-toolchain-precedence]: https://github.com/rust-lang/rustup/blob/master/README.md#override-precedence -[MUSL C standard library]: https://musl.libc.org/ ## SGXS Utilities diff --git a/docs/rofl/trust-root.md b/docs/rofl/trust-root.md index 3771e48774..153e552c6e 100644 --- a/docs/rofl/trust-root.md +++ b/docs/rofl/trust-root.md @@ -5,7 +5,7 @@ _consensus trust root_. The preconfigured trust root is valid for the current deployment of Sapphire Testnet. This chapter briefly describes what the trust root is, how it can be securely derived and configured in your ROFL app. -[ROFL app example]: app.md +[ROFL app example]: app.mdx ## The Root of Trust diff --git a/examples/runtime-sdk/rofl-oracle/oracle/README.md b/examples/runtime-sdk/rofl-oracle/oracle/README.md index ff81794b08..a3a4cad7af 100644 --- a/examples/runtime-sdk/rofl-oracle/oracle/README.md +++ b/examples/runtime-sdk/rofl-oracle/oracle/README.md @@ -37,5 +37,5 @@ npx hardhat oracle-query 0x5FbDB2315678afecb367f032d93F642f64180aa3 --network sa For more information check out the [ROFL tutorial]. -[ROFL tutorial]: https://github.com/oasisprotocol/oasis-sdk/blob/main/docs/rofl/app.md +[ROFL tutorial]: https://github.com/oasisprotocol/oasis-sdk/blob/main/docs/rofl/app.mdx