# Claude Code — Dockerized

A minimal, guardrailed container for running Claude Code. The home
directory and project folder are volumes, keeping your Claude install
and credentials separate from any specific project.

## Setup

```bash
# 1. Build the image
docker compose build

# 2. Export your API key (or put it in a .env file)
export ANTHROPIC_API_KEY=sk-ant-...

# 3. First run — installs Claude Code into the home volume, then drops you
#    into an interactive shell inside the default ./code directory
docker compose run --rm claude-code
```

On first start the entrypoint runs the native installer and places the
binary in the `claude-home` named volume (under `/home/coder/.local/bin`).
Subsequent starts skip the install and launch immediately.

## Switching projects

Point `PROJECT_DIR` at any directory on your host:

```bash
PROJECT_DIR=/path/to/myproject docker compose run --rm claude-code
```

Or set it in a `.env` file:

```
ANTHROPIC_API_KEY=sk-ant-...
PROJECT_DIR=/Users/me/projects/my-app
```

Then just:

```bash
docker compose run --rm claude-code
```

## Starting Claude Code

Once inside the container shell:

```bash
claude          # start an interactive session in the current directory
claude --help   # show available options
claude doctor   # diagnose installation issues
```

## Volumes

| Volume                | Purpose                                                   |
| --------------------- | --------------------------------------------------------- |
| `claude-home` (named) | Persists Claude Code binary, config, and auth credentials |
| `$PROJECT_DIR` (bind) | Your project code — swap freely between sessions          |

To wipe the Claude install and start fresh:

```bash
docker compose down -v   # removes the claude-home volume
```

## Security notes

- Runs as a non-root user (`coder`, uid 1001)
- All Linux capabilities are dropped except `NET_BIND_SERVICE`
- Privilege escalation is disabled (`no-new-privileges`)
- The container has no network restrictions beyond what Docker provides —
  add a custom network or `--network none` with `--add-host` if you want
  to lock that down further

## Connecting to a host PostgreSQL database

The container can reach a PostgreSQL server running on the host, but
`127.0.0.1` inside the container refers to the container itself, not the
host. The solution is to connect via the Docker bridge gateway IP instead,
which both the host and the container can see.

### 1. Find the gateway IP

```bash
docker network inspect bridge | grep Gateway
```

This is typically `172.17.0.1`. Use the value specific to your machine
in all steps below.

### 2. Configure PostgreSQL on the host

Edit `/etc/postgresql/<version>/main/postgresql.conf`:

```
listen_addresses = 'localhost,172.17.0.1'
```

Edit `/etc/postgresql/<version>/main/pg_hba.conf` and add:

```
host    all    all    172.17.0.0/16    scram-sha-256
```

Restart PostgreSQL:

```bash
sudo systemctl restart postgresql
```

### 3. Configure your app

Use the gateway IP as the database host. Since it is reachable from both
the host and the container, a single `DATABASE_URL` works in both contexts:

```
DATABASE_URL=postgresql://user:password@172.17.0.1:5432/mydb
```

Set this in your `.env` file or shell profile on the host, and pass it
through in `docker-compose.yml`:

```yaml
environment:
  - DATABASE_URL=${DATABASE_URL}
```

### Collation version warning

If you see a warning like:

```
WARNING: database "mydb" has a collation version mismatch
DETAIL: The database was created using collation version 2.41, but the
operating system provides version 2.42.
```

This is caused by the container's glibc version differing from the host's.
It is a warning only and will not break anything. To silence it, run once
on the host:

```bash
psql -d mydb -c "ALTER DATABASE mydb REFRESH COLLATION VERSION;"
```

Note: the warning will reappear inside the container because its glibc
version differs from the host. The long-term fix is to rebase the Docker
image on the same Ubuntu release as the host so glibc versions match.