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'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 --help2) 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 acmeCredentials are saved to ~/.river/config.json, so every later command
runs authenticated. Confirm at any time:
$ river auth status
Workspace: acme
API key: rqk_…9f31For 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 --json3) 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: acmeDocker 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 SucceededThat'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:latestTwo 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/amd64only; 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.liThe 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 downA few behaviors worth knowing:
- Routing port: River reads the image's
EXPOSEmetadata and routes to the smallest declared port (falls back to 80). An image listening on:8080shouldEXPOSE 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 externaland an image likeghcr.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:
| Secret | Value |
|---|---|
RIVER_WORKSPACE | your workspace ID (e.g. acme) |
RIVER_API_KEY | a 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/amd64inbuild-push-actionis the buildx equivalent of the--platformflag from step 4 — the #1 cause ofno matching manifestfailures 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 (viaRIVER_API_KEY). Rotate it in the dashboard and CI rotates with it. - Idempotency:
river containers list --jsonis 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 plainjqinstead 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.
Enjoyed this post?
Read more from the blog