All posts
Engineering

Ship Containers with River

River's container apps take a plain Docker image, run it on the platform's runtime, and give it a public HTTPS URL - no Let's Encrypt wiring, no ingress YAML

River Team
October 12, 20265 min read
Ship Containers with River

River's container apps take a plain Docker image, run it on the platform's runtime, and give it a public HTTPS URL -no Let's Encrypt wiring, no ingress YAML. This post walks the whole path: installing the CLI, authenticating both the River API and the built-in Docker registry, pushing an image, and deploying it — then automates all of it with a GitHub Actions workflow.

Everything below runs against a River workspace (e.g. acme.river.li); every workspace gets its own private registry at <workspace>-r.river.li.

1) Install the CLI

The CLI is river, distributed on npm (Node.js ≥ 18):

npm install -g @brian-bill/river
river --help

2) Authenticate with River

Create an API key in your workspace dashboard (Settings → API keys), then:

river auth login
# Workspace ID: acme
# API key:      ********      # starts with rqk_
# Logged in as workspace acme

Credentials are saved to ~/.river/config.json, so every later command runs authenticated. Confirm at any time:

$ river auth status
Workspace: acme
API key:   rqk_…9f31

For scripts and CI you can bypass the config file by passing the credentials inline — the global --workspace and --api-key flags attach to any command:

river --workspace acme --api-key "$RIVER_API_KEY" containers list --json

3) Log in to the workspace Docker registry

Every workspace ships an OCI registry. The CLI prints the endpoint and the packaged login command:

$ river containers registry
registry endpoint: acme-r.river.li
username: acme

Docker clients authenticate with your API key as the password (username is the workspace slug). Use --password-stdin rather than -p so the key never lands in your shell history:

river containers registry   # note the endpoint
echo "$RIVER_API_KEY" | docker login acme-r.river.li -u acme --password-stdin
# Login Succeeded

That's the only auth step needed — the registry sits behind River's ForwardAuth wall, so the API key is all you ever manage.

4) Build and push an image

Images must target linux/amd64 — the platform's servers are x86_64. On an Apple Silicon Mac, docker build defaults to linux/arm64, which pushes fine but fails at pull time with no matching manifest for linux/amd64. Always pass the platform:

docker build --platform linux/amd64 -t acme-r.river.li/web:latest .
docker image inspect acme-r.river.li/web:latest --format '{{.Architecture}}'
# amd64
docker push acme-r.river.li/web:latest

Two naming rules:

  • Reference the image exactly as pushed (<endpoint>/<name>:<tag>) — the app row stores that reference and the deploy pull re-uses it.
  • linux/amd64 only; multi-arch manifests work too, as long as amd64 is in the list.

5) Create and deploy the container app

$ river containers create --name web --image acme-r.river.li/web:latest --source registry
✔ Container app created: web (971bedbc-794e-4b82-b8fa-e680c2a6d8ad)
 
$ river containers deploy 971bedbc-794e-4b82-b8fa-e680c2a6d8ad
Deployed.
FQDN: acme-c-web-7c2a91.river.li

The deploy step pulls your image from the private registry with your workspace credentials, starts the container on the platform network, and publishes its route — the app gets a public hostname like acme-c-web-7c2a91.river.li. That FQDN is HTTPS from the moment you open it — no further wiring.

Useful day-two commands:

river containers list                          # status + FQDN for every app
river containers logs  --tail 100 971bedbc     # container logs
river containers stop 971bedbc                 # stop (keeps the app)
river containers delete 971bedbc               # tear the app down

A few behaviors worth knowing:

  • Routing port: River reads the image's EXPOSE metadata and routes to the smallest declared port (falls back to 80). An image listening on :8080 should EXPOSE 8080.
  • Env vars: pass a JSON object at create time: river containers create --name web ... --env '{"APP_MODE":"prod"}'
  • External images: any public image deploys without a push at all — create the app with --source external and an image like ghcr.io/org/app:tag.
  • Redeploys: re-push the same tag, then river containers deploy <id> again — it re-pulls and replaces the running container.

6) Automate it — GitHub Actions CI/CD

The same pipeline as code: build on push, push the image to the workspace registry, then deploy the container app. Three repository secrets:

SecretValue
RIVER_WORKSPACEyour workspace ID (e.g. acme)
RIVER_API_KEYa River API key (rqk_…)
(no registry password — it's the same key)

.github/workflows/deploy.yml:

name: Build, push & deploy
 
on:
  push:
    branches: [main]
  workflow_dispatch:
 
env:
  RIVER_WORKSPACE: ${{ secrets.RIVER_WORKSPACE }}
  RIVER_API_KEY: ${{ secrets.RIVER_API_KEY }}
  REGISTRY: ${{ secrets.RIVER_WORKSPACE }}-r.river.li
  IMAGE: ${{ secrets.RIVER_WORKSPACE }}-r.river.li/web
  APP_NAME: web
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - uses: docker/setup-buildx-action@v3
 
      - name: Log in to the River registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ secrets.RIVER_WORKSPACE }}
          password: ${{ secrets.RIVER_API_KEY }}
 
      - name: Build and push (linux/amd64)
        uses: docker/build-push-action@v6
        with:
          context: .
          platforms: linux/amd64
          push: true
          tags: ${{ env.IMAGE }}:latest
 
      - name: Install the River CLI
        run: npm install -g @brian-bill/river
 
      - name: Deploy
        run: |
          set -euo pipefail
 
          # reuse the app if it exists, else create it
          APP_ID=$(river containers list --json 2>/dev/null \
                     | jq -r --arg n "$APP_NAME" \
                       '(.apps // [])[] | select(.name == $n) | .id' | head -n1)
 
          if [ -z "$APP_ID" ]; then
            APP_ID=$(river containers create \
                       --name "$APP_NAME" \
                       --image "$IMAGE:latest" \
                       --source registry --json \
                       | jq -r '.app.id')
            echo "created $APP_ID"
          fi
 
          river containers deploy "$APP_ID"

Notes on the workflow:

  • Platform: platforms: linux/amd64 in build-push-action is the buildx equivalent of the --platform flag from step 4 — the #1 cause of no matching manifest failures when building from Apple silicon developers' machines or default runners configured for arm64.
  • One credential, two uses: the same API key authenticates the docker push (via login-action) and the CLI deploy (via RIVER_API_KEY). Rotate it in the dashboard and CI rotates with it.
  • Idempotency: river containers list --json is the app store; the deploy step creates only on first run and then re-deploys the existing app forever after.
  • JSON mode: every CLI command honors --json, so the workflow parses with plain jq instead of scraping the pretty output.

Wrap-up

The whole product surface is four commands you type once per app (docker login, docker build, docker push, river containers create) plus river containers deploy every release. Everything after that — HTTPS routing, certs, pulls, restarts — is the platform's job. If you'd rather let AI do it, Lily (the assistant in the dashboard) accepts create_container, build_image and deploy_container actions and wires the same pipeline from a sentence.

containersdocker

Enjoyed this post?

Read more from the blog