From e56d6510e90690ce525411b4065764c7e0aa4ee0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Ber=C4=8Di=C4=8D?= Date: Thu, 14 Nov 2024 02:51:33 +0200 Subject: [PATCH 1/2] docker: Add Dockerfile for developing ROFL on macOS --- .github/workflows/rofl-dev-image.yml | 83 ++++++++++++++++++++++++++++ docker/rofl-dev/Dockerfile | 14 +++++ docs/rofl/app.md | 35 ++++++++++-- docs/rofl/prerequisites.md | 36 +++++++++--- 4 files changed, 154 insertions(+), 14 deletions(-) create mode 100644 .github/workflows/rofl-dev-image.yml create mode 100644 docker/rofl-dev/Dockerfile 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.md index 18a4b2fc8a..deadac61c9 100644 --- a/docs/rofl/app.md +++ b/docs/rofl/app.md @@ -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/prerequisites.md b/docs/rofl/prerequisites.md index c910dcdb89..05816a5c52 100644 --- a/docs/rofl/prerequisites.md +++ b/docs/rofl/prerequisites.md @@ -12,6 +12,27 @@ If you already have everything set up, feel free to skip to the [next chapter]. [next chapter]: app.md +:::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 The following is a list of prerequisites required to start developing using the @@ -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 From 53b2d9d3042fc7572b0871a6fa3297cd24fdc2b7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Ber=C4=8Di=C4=8D?= Date: Tue, 3 Dec 2024 15:41:19 +0100 Subject: [PATCH 2/2] docs: Rename rofl app.md to app.mdx Since it now uses docusaurus extensions. --- docs/rofl/{app.md => app.mdx} | 0 docs/rofl/deployment.md | 2 +- docs/rofl/prerequisites.md | 2 +- docs/rofl/trust-root.md | 2 +- examples/runtime-sdk/rofl-oracle/oracle/README.md | 2 +- 5 files changed, 4 insertions(+), 4 deletions(-) rename docs/rofl/{app.md => app.mdx} (100%) diff --git a/docs/rofl/app.md b/docs/rofl/app.mdx similarity index 100% rename from docs/rofl/app.md rename to docs/rofl/app.mdx 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 05816a5c52..7fe9ab4905 100644 --- a/docs/rofl/prerequisites.md +++ b/docs/rofl/prerequisites.md @@ -10,7 +10,7 @@ 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 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