D 2026-03-15T20:40:12.782
L NATS\sServer\s—\sDocker\sImage
N text/x-markdown
U dmestas
W 6634
# NATS Server — Docker Image

A minimal Docker image for running the fossil-nats server in a container.
Image size: **24 MB** (based on `nats:2.10.22-alpine`, no extra packages added).

See [NATS Server — Setup & Architecture](NATS Server — Setup & Architecture) for the full design.

---

## How It Works

``` pikchr
    right

    BLD: box "docker build" fill 0xfff0cc width 1.4 height 0.4 rad 4px
    move 0.15
    arrow color 0x888888
    move 0.15
    IMG: box "fossil-nats:2.10.22" color white fill 0x2a4a8a width 1.8 height 0.4 rad 4px

    down
    ENV: box "OPERATOR_JWT" fill 0xd0f0d0 width 1.4 height 0.35 rad 4px at IMG.s + (-1.0, -0.6)
    SYS: box "SYS_ACCOUNT_KEY" fill 0xd0f0d0 width 1.4 height 0.35 rad 4px at IMG.s + (0.6, -0.6)
    TLS: box "/var/nats/tls/ (ro)" fill 0xd0eeff width 1.4 height 0.35 rad 4px at IMG.s + (-1.0, -1.1)
    JWT: box "/var/nats/jwt/ (rw)" fill 0xd0eeff width 1.4 height 0.35 rad 4px at IMG.s + (0.6, -1.1)
    JST: box "/var/nats/jetstream/ (rw)" fill 0xd0eeff width 1.7 height 0.35 rad 4px at IMG.s + (-0.15, -1.6)

    arrow from ENV.n to IMG.s + (-1.0, -0.05) color 0x888888 <-
    arrow from SYS.n to IMG.s + (0.6, -0.05)  color 0x888888 <-
    arrow from TLS.n to IMG.s + (-1.0, -0.05) color 0x888888 <-
    arrow from JWT.n to IMG.s + (0.6, -0.05)  color 0x888888 <-
    arrow from JST.n to IMG.s + (-0.15, -0.05) color 0x888888 <-

    text "env vars" small at IMG.s + (-0.2, -0.35)
    text "volumes" small at IMG.s + (-0.2, -0.85)

    right
    EP: box "docker-entrypoint.sh" fill 0xf0f0f0 width 1.8 height 0.4 rad 4px at IMG.e + (0.8, -0.3)
    arrow from IMG.e right 0.15 then to EP.w color 0x888888
    move 0.15
    arrow color 0x888888
    NS: box "nats-server -c /tmp/nats-server.conf" fill 0xd0f0d0 width 2.8 height 0.4 rad 4px
```

The entrypoint:
1. Sources `/etc/nats/operator.env` if present (mounted volume)
2. Validates `OPERATOR_JWT` and `SYS_ACCOUNT_KEY` are set
3. Renders `nats-server.conf.template` → `/tmp/nats-server.conf` using `sed`
4. `exec nats-server -c /tmp/nats-server.conf`

No extra packages are installed — config substitution uses `sed` from busybox (already in `nats:alpine`).

---

## Files

| File | Purpose |
|------|---------|
| `nats/Dockerfile` | Image definition |
| `nats/docker-entrypoint.sh` | Startup script — renders config, starts server |
| `nats/nats-server.conf.template` | Config template with `$OPERATOR_JWT` / `$SYS_ACCOUNT_KEY` |
| `nats/.dockerignore` | Excludes `creds/` from build context |

---

## Build

```sh
cd ~/Projects/infra/nats
sudo docker build -t fossil-nats:2.10.22 .
```

---

## Run

### Get the required values

```sh
# Operator JWT (already in /etc/nats/operator.env on the server)
OPERATOR_JWT=$(sudo sed 's/OPERATOR_JWT=//' /etc/nats/operator.env)

# SYS account public key
SYS_ACCOUNT_KEY=$(nsc describe account --name SYS 2>&1 \
  | grep 'Account ID' \
  | sed 's/.*| Account ID *| *\([^ ]*\) .*/\1/')
```

### Start the container

```sh
sudo docker run -d \
    --name fossil-nats \
    -p 4222:4222 \
    -e OPERATOR_JWT="$OPERATOR_JWT" \
    -e SYS_ACCOUNT_KEY="$SYS_ACCOUNT_KEY" \
    -v /var/nats/tls:/var/nats/tls:ro \
    -v /var/nats/jwt:/var/nats/jwt \
    -v /var/nats/jetstream:/var/nats/jetstream \
    fossil-nats:2.10.22
```

Or mount `operator.env` as a file instead of env vars:

```sh
sudo docker run -d \
    --name fossil-nats \
    -p 4222:4222 \
    -e SYS_ACCOUNT_KEY="$SYS_ACCOUNT_KEY" \
    -v /etc/nats/operator.env:/etc/nats/operator.env:ro \
    -v /var/nats/tls:/var/nats/tls:ro \
    -v /var/nats/jwt:/var/nats/jwt \
    -v /var/nats/jetstream:/var/nats/jetstream \
    fossil-nats:2.10.22
```

---

## Verify

```sh
# Check logs
sudo docker logs fossil-nats

# Connect and list streams
nats stream ls \
    --server tls://sync.craftdesign.group:4222 \
    --creds ~/Projects/infra/nats/creds/edgesync-admin.creds

# Publish a test message
nats pub fossil.edgesync.test "hello" \
    --server tls://sync.craftdesign.group:4222 \
    --creds ~/Projects/infra/nats/creds/edgesync-admin.creds
```

---

## Network Requirements

Before running the container, the operator must complete these steps:

### 1. Open port 4222 in the firewall

**On vps-nbg1 (UFW):**
```sh
sudo ufw allow 4222/tcp
sudo ufw status | grep 4222
```

**On another host (varies by provider):**
- Open TCP port 4222 inbound in your cloud provider's security group / firewall rule.
- There is no other NATS port to open for single-node TLS-only setup.

### 2. Add a DNS A record

Clients connect using the hostname in the TLS cert. The cert is currently issued for `sync.craftdesign.group`. For a **new host**, either:

| Option | When to use | Steps |
|--------|-------------|-------|
| Reuse the existing cert | Deploying on vps-nbg1 or a machine that can serve `sync.craftdesign.group` | Mount `/var/nats/tls` — no DNS change needed on the host |
| Issue a new cert for your domain | Deploying on a new server with its own hostname | Run `install.sh` (Phase 1) on that server — it issues a cert for the `DOMAIN` you set |
| Self-signed cert (dev/test only) | Local dev machine, no public DNS | Generate a self-signed cert and mount it; clients must use `--tlsca` |

For the standard case (new server, new domain):
1. Create DNS A record: `your-nats.example.com` → `<server-ip>`
2. Set `DOMAIN=your-nats.example.com` in `install.sh` before running
3. The TLS cert is issued automatically via acme.sh DNS-01

### 3. Verify DNS before starting

```sh
# From any machine — must resolve before TLS cert is issued
nslookup your-nats.example.com
# or
dig +short your-nats.example.com
```

---

## TLS Note

The cert baked into the server config is for `sync.craftdesign.group` (Let's Encrypt, auto-renewed via acme.sh on the host). When running the container:

- **On vps-nbg1**: mount `/var/nats/tls` — the cert is already there, and the DNS resolves correctly.
- **Elsewhere**: replace `/var/nats/tls` with a cert valid for your hostname, and update the `cert_file` / `key_file` paths in `nats-server.conf.template` if they differ.

Clients must connect using the hostname the cert was issued for (`sync.craftdesign.group`), not by IP, for TLS verification to pass.

---

## On This Server (vps-nbg1)

NATS runs under **systemd** (not Docker) in production — see [NATS Server — Operations Runbook](NATS Server — Operations Runbook). The Docker image is provided for:

- Deploying to a second node in a future cluster
- Running NATS on a dev machine or CI runner that connects as a leaf node
- Testing config changes in isolation before applying to the production systemd instance

Z eb5917bf1db6d49d58dc14ee848d0745