Overhaul docs: fix docker-compose to use env_file, add AWS SSO setup guide, clarify exec -u developer

2026-04-10 20:10:18 +02:00
parent fa4739e061
commit 73e94c7e54
2 changed files with 125 additions and 51 deletions
@@ -55,16 +55,12 @@ docker exec -it -u developer devbox bash
 docker rm -f devbox
 ```

-With docker-compose this is simpler:
-
-```bash
-docker compose up -d
-docker compose exec -u developer devbox opencode     # terminal 1
-docker compose exec -u developer devbox bash         # terminal 2
-```
+> **Note:** Always use `-u developer` with `docker exec` — the container starts as root for UID adjustment, then drops to `developer`. Without `-u developer`, exec runs as root.

 ## Environment Variables

+All configuration is done via environment variables, typically stored in a `.env` file.
+
 ### Provider Configuration

 | Variable | Description | Default |
@@ -87,14 +83,7 @@ Set the key matching your provider:
 | Variable | Description | Default |
 |---|---|---|
 | `AWS_REGION` | AWS region | `us-east-1` |
-| `AWS_PROFILE` | AWS profile name | `default` |
-
-For SSO authentication, start with `bash` and run:
-
-```bash
-aws sso login --sso-session <your-session> --use-device-code
-opencode
-```
+| `AWS_PROFILE` | AWS SSO profile name | `default` |

 ### Git

@@ -114,14 +103,66 @@ The entrypoint automatically detects the owner of `/workspace` and adjusts the c
 | `USER_UID` | Container user UID | Auto-detect from `/workspace` owner |
 | `USER_GID` | Container user GID | Auto-detect from `/workspace` owner |

+## Initial Setup
+
+### 1. Create a project directory
+
 ```bash
-docker run -it --rm \
-  -e USER_UID=$(id -u) \
-  -e USER_GID=$(id -g) \
-  -v ~/projects:/workspace \
-  joakimp/opencode-devbox:latest
+mkdir -p ~/projects
 ```

+### 2. Create a `.env` file
+
+Create a `.env` file with your configuration. Examples for each provider:
+
+**Anthropic:**
+```bash
+OPENCODE_PROVIDER=anthropic
+ANTHROPIC_API_KEY=sk-ant-...
+GIT_USER_NAME=Your Name
+GIT_USER_EMAIL=you@example.com
+```
+
+**OpenAI:**
+```bash
+OPENCODE_PROVIDER=openai
+OPENAI_API_KEY=sk-...
+GIT_USER_NAME=Your Name
+GIT_USER_EMAIL=you@example.com
+```
+
+**AWS Bedrock (SSO):**
+```bash
+OPENCODE_PROVIDER=amazon-bedrock
+OPENCODE_MODEL=amazon-bedrock/anthropic.claude-sonnet-4-5-v1
+AWS_REGION=eu-west-1
+AWS_PROFILE=your-profile-name
+GIT_USER_NAME=Your Name
+GIT_USER_EMAIL=you@example.com
+```
+
+### 3. AWS SSO setup (Bedrock users only)
+
+AWS SSO requires a `~/.aws/config` file on the host with your SSO session configuration. If you already have this on another machine, copy it:
+
+```bash
+scp -r user@other-machine:~/.aws ~/.aws
+```
+
+Or configure from scratch:
+
+```bash
+aws configure sso
+```
+
+You'll be prompted for:
+- SSO session name
+- SSO start URL
+- SSO region
+- Registration scopes (typically `sso:account:access`)
+
+The `~/.aws` directory must be mounted into the container (see docker-compose example below).
+
 ## Data Storage and Persistence

 Understanding what survives container restarts and what doesn't:
@@ -130,27 +171,16 @@ Understanding what survives container restarts and what doesn't:
 |---|---|---|---|
 | `/workspace` | Host bind mount | ✅ Yes — lives on host | Your project files |
 | `/home/developer/.ssh` | Host bind mount (ro) | ✅ Yes — lives on host | SSH keys |
+| `/home/developer/.aws` | Host bind mount | ✅ Yes — lives on host | AWS credentials/SSO cache |
 | `/home/developer/.local/share/opencode` | Named volume (if configured) | ✅ Yes — Docker volume | Session history, memory, auth tokens |
 | `/home/developer/.config/opencode/opencode.json` | Generated by entrypoint | ❌ No — regenerated each start | Provider config, MCP server definitions |
-| `/home/developer/.aws` | Host bind mount (if configured) | ✅ Yes — lives on host | AWS credentials/SSO cache |

 ### Key points

 - **Project files** (`/workspace`) are always safe — they're your host filesystem.
 - **opencode config** is auto-generated from `OPENCODE_PROVIDER` env var on each start. It only sets provider and model — no MCP servers. To persist MCP server config, mount your own config file (see Custom opencode Config below).
 - **opencode data** (session history, memory) is lost with `--rm` unless you add a named volume.
- **AWS SSO tokens** are stored inside the container and lost on restart. Re-run `aws sso login` after restarting.
-
-### Persisting opencode data
-
-Add a named volume to keep session history and memory between runs:
-
-```bash
-docker run -it --rm \
-  -v opencode-data:/home/developer/.local/share/opencode \
-  ... \
-  joakimp/opencode-devbox:latest
-```
+- **AWS SSO tokens** persist across restarts when `~/.aws` is mounted (recommended for Bedrock users).

 ## Custom opencode Config

@@ -167,16 +197,19 @@ When a config file is mounted, the `OPENCODE_PROVIDER` auto-config is skipped.

 ## Using docker-compose

-Create a `docker-compose.yml` and a `.env` file in the same directory:
+Create a directory with a `docker-compose.yml` and a `.env` file:

 ```bash
 mkdir opencode-devbox && cd opencode-devbox
 ```

-`.env` — your secrets and settings (never commit this):
+`.env` — your settings (never commit this):

 ```bash
-ANTHROPIC_API_KEY=sk-ant-...
+OPENCODE_PROVIDER=amazon-bedrock
+OPENCODE_MODEL=amazon-bedrock/anthropic.claude-sonnet-4-5-v1
+AWS_REGION=eu-west-1
+AWS_PROFILE=your-profile-name
 GIT_USER_NAME=Your Name
 GIT_USER_EMAIL=you@example.com
 ```
@@ -189,33 +222,45 @@ services:
    image: joakimp/opencode-devbox:latest
    stdin_open: true
    tty: true
+    env_file:
+      - .env
    environment:
      - TERM=xterm-256color
-      - OPENCODE_PROVIDER=anthropic
-      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
-      - GIT_USER_NAME=${GIT_USER_NAME}
-      - GIT_USER_EMAIL=${GIT_USER_EMAIL}
    volumes:
      - ~/projects:/workspace
      - ~/.ssh:/home/developer/.ssh:ro
      - devbox-data:/home/developer/.local/share/opencode
+      # Mount AWS config for Bedrock SSO (required for amazon-bedrock provider)
+      # - ~/.aws:/home/developer/.aws
      # Optional: mount your own opencode config (MCP servers, custom models, etc.)
      # - ./opencode.json:/home/developer/.config/opencode/opencode.json:ro
      # Optional: mount opencode skills from host
      # - ~/.config/opencode/skills:/home/developer/.config/opencode/skills:ro
      # - ~/.agents/skills:/home/developer/.agents/skills:ro
-      # Optional: AWS credentials/SSO config (not read-only — SSO writes token cache)
-      # - ~/.aws:/home/developer/.aws

 volumes:
  devbox-data:
 ```

-Docker Compose automatically loads `.env` from the same directory as the compose file. The `${VAR}` references are substituted with values from `.env`.
+Docker Compose loads `.env` automatically from the same directory. All variables from `.env` are passed to the container via `env_file`. Do **not** hardcode provider settings in the `environment:` section — use `.env` instead.

 Then:

 ```bash
+# Start in background
+docker compose up -d
+
+# Open a shell (always use -u developer with exec)
+docker compose exec -u developer devbox bash
+
+# For Bedrock: authenticate, then start opencode
+aws sso login --sso-session <your-session> --use-device-code
+opencode
+
+# Or run opencode directly (if no SSO needed)
+docker compose exec -u developer devbox opencode
+
+# One-shot mode (creates and removes container)
 docker compose run --rm devbox        # direct to opencode
 docker compose run --rm devbox bash   # interactive shell
 ```