Docker Builds

Overview

Docker image builds for legacy services happen on ai.matthewstevens.org (SSH alias: ai). The NAS (a1.matthewstevens.org) is a deployment target ONLY – never build images there.

Important: New services should use Nix builds per the Sovereign Architecture SOP. Docker builds are only for legacy services that have not been migrated.

Build Server: ai.matthewstevens.org

SSH Access

1

ssh ai

Environment Setup

The build server requires explicit PATH configuration:

1

export PATH=/usr/local/bin:/opt/homebrew/bin:$HOME/.orbstack/bin:$PATH

This is required in every session. The default shell PATH does not include Docker/OrbStack binaries.

Multiarch Builder

A multiarch buildx builder is preconfigured for cross-platform builds:

1
2

docker buildx ls
# Should show "multiarch" builder with linux/amd64 and linux/arm64 platforms

If the builder does not exist:

1
2

docker buildx create --name multiarch --use --platform linux/amd64,linux/arm64
docker buildx inspect multiarch --bootstrap

Procedure: Build and Push Image

For Docker Hub (Legacy/Auxiliary)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

ssh ai
export PATH=/usr/local/bin:/opt/homebrew/bin:$PATH

cd /path/to/project

# Build and push in one step
docker buildx build \
  --platform linux/amd64 \
  --builder multiarch \
  --push \
  -t applepublicdotcom/<image-name>:<tag> \
  .

For Amazon ECR (Phenom Drop)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

ssh ai
export PATH=/usr/local/bin:/opt/homebrew/bin:$PATH

# Authenticate with ECR
AWS_ACCOUNT_ID=$(pass aws/account-id)
AWS_REGION="us-east-1"
aws ecr get-login-password --region ${AWS_REGION} | \
  docker login --username AWS --password-stdin \
  ${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com

# Build and push
docker buildx build \
  --platform linux/amd64 \
  --builder multiarch \
  --push \
  -t ${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com/<repo>:<tag> \
  .

Registry Conventions

Critical Rules

1. NEVER use the applepublic namespace – that is the public namespace. Always use applepublicdotcom (private).
2. NEVER build on the NAS – the NAS pulls pre-built images only.
3. NEVER push to Docker Hub for production – use Scaleway Container Registry via Skopeo.

NAS Deployment

The NAS (a1.matthewstevens.org) only pulls and runs pre-built images:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

ssh a1

# Pull the image
docker pull applepublicdotcom/<image-name>:<tag>

# Run
docker run -d \
  --name <container-name> \
  --restart unless-stopped \
  -p <host-port>:<container-port> \
  -e ENV_VAR=value \
  applepublicdotcom/<image-name>:<tag>

Testing Pipeline

The correct pipeline for Docker-based services is:

1. Build on ai.matthewstevens.org
2. Push with :testing tag
3. Deploy to NAS testing server
4. Verify on testing server
5. Run full test suite
6. Retag as :production
7. Deploy to production via GitHub Actions

No image receives a :production tag without ALL tests passing.

Troubleshooting

• docker: command not found: Set PATH explicitly: export PATH=/usr/local/bin:/opt/homebrew/bin:$HOME/.orbstack/bin:$PATH
• Builder not found: Recreate with docker buildx create --name multiarch --use
• Push authentication failure: Re-login to the appropriate registry
• Platform mismatch: Always specify --platform linux/amd64 for NAS/server deployments