Docker

The Docker image provides a complete Rust + WASM toolchain so you can compile Dilithia smart contracts without installing Rust locally. It is also designed as a small contract compilation service: by default it runs the Dilithia contract CLI against the mounted /workspace.

When to Use Docker

• You do not have (or do not want) a local Rust installation
• You need reproducible builds across different developer machines
• You are setting up CI/CD and want a consistent build environment

Build the Image

docker build -f contract-tools/docker/Dockerfile -t dilithia/contract-builder .

The image is based on rust:1.88.0-bookworm and includes:

• The wasm32-unknown-unknown Rust target
• pinned upstream Binaryen (wasm-opt) for WASM optimization
• The dilithia-contract CLI installed in the image
• A pre-warmed Cargo cache to reduce the first build penalty

Compile a Contract

Mount your project directory into /workspace and run:

docker run --rm -v "$(pwd)":/workspace dilithia/contract-builder

The default entrypoint runs:

dilithia-contract build --path /workspace

Your compiled artifact will appear at:

target/wasm32-unknown-unknown/release/<contract_name>.wasm

Run Other CLI Commands

Because the image entrypoint is dilithia-contract, you can invoke any subcommand directly:

docker run --rm -v "$(pwd)":/workspace dilithia/contract-builder init --name my_contract
docker run --rm -v "$(pwd)":/workspace dilithia/contract-builder build --path /workspace --output json

Override the Entrypoint

To drop into a shell for debugging:

docker run --rm -it -v "$(pwd)":/workspace --entrypoint bash dilithia/contract-builder

CI/CD Integration

GitHub Actions

name: Build Contract

on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build contract WASM
        run: |
          docker build -f contract-tools/docker/Dockerfile -t dilithia/contract-builder .
          docker run --rm -v ${{ github.workspace }}:/workspace dilithia/contract-builder

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: contract-wasm
          path: target/wasm32-unknown-unknown/release/*.wasm

GitLab CI

build-contract:
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker build -f contract-tools/docker/Dockerfile -t dilithia/contract-builder .
    - docker run --rm -v "$(pwd)":/workspace dilithia/contract-builder
  artifacts:
    paths:
      - target/wasm32-unknown-unknown/release/*.wasm

Cache Mounts for Faster Rebuilds

The image stores Cargo and target caches under /cache, so you can persist them across runs:

docker run --rm \
  -v "$(pwd)":/workspace \
  -v dilithia-contract-cargo:/cache/cargo \
  -v dilithia-contract-target:/cache/target \
  dilithia/contract-builder

This is especially useful in CI runners or long-lived local environments.

Image Details

The Dockerfile performs the following steps:

1. Starts from rust:1.88.0-bookworm
2. Installs the wasm32-unknown-unknown target via rustup
3. Installs build prerequisites via apt
4. Downloads a pinned upstream Binaryen release and installs wasm-opt
5. Copies contract-tools into the image and resolves dilithia-sdk-rust from crates.io during install
6. Installs the dilithia-contract CLI into the image
7. Warms the Cargo cache with a minimal Dilithia contract build
8. Sets /workspace as the working directory
9. Sets the entrypoint to dilithia-contract
10. Sets the default command to build --path /workspace