# SAAC Deployment — How Your App Gets Built

> **READ THIS FIRST.** This file explains exactly how SAAC deploys your app.
> Understanding this will save you hours of debugging.

## The Build Process

When you run `saac deploy`, the daemon executes these exact commands in your repo:

```bash
docker compose -f docker-compose.yml -f docker-compose.saac.yml build
docker compose -p saac-{uuid} -f docker-compose.yml -f docker-compose.saac.yml up -d
```

**Your `docker-compose.yml` and `Dockerfile` ARE used.** The auto-generated `docker-compose.saac.yml` overlay ADDS labels, networks, and restart policy — it never replaces your config.

## Required Files

Your repo MUST have:
1. `docker-compose.yml` — defines services (app, postgres, redis)
2. `Dockerfile` — referenced by the build directive in compose

## The 5 Rules

### Rule 1: Use `expose`, NEVER `ports`

Traefik reverse proxy handles all external routing. Host port bindings conflict with other apps.

```yaml
# WRONG — will conflict with other apps on the server
ports:
  - "3000:3000"

# CORRECT — Traefik routes traffic to this port
expose:
  - "3000"
```

### Rule 2: Database host = service name, NOT localhost

In Docker Compose, services talk to each other by service name.

```yaml
# WRONG — localhost means "inside this container" in Docker
DATABASE_URL: postgresql://postgres:postgres@localhost:5432/mydb

# CORRECT — "postgres" is the service name in docker-compose.yml
DATABASE_URL: postgresql://postgres:postgres@postgres:5432/mydb

# ALSO CORRECT — if using shared org database
DATABASE_URL: postgresql://postgres:postgres@postgres.internal:5432/mydb
```

### Rule 3: Dockerfile must produce a running container

```dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
# If TypeScript: RUN npm run build
CMD ["node", "server.js"]
```

Key points:
- `npm install` happens INSIDE the container (not on host)
- `COPY . .` copies your source into the container
- `CMD` must start your app
- For TypeScript: add `RUN npm run build` before CMD, use `CMD ["node", "dist/server.js"]`

### Rule 4: Keep it simple — iterate incrementally

**Start with the working template, then add features one at a time.**

DO NOT:
- Replace Express with a full TypeScript/Prisma/monorepo stack in one commit
- Create complex multi-stage Dockerfiles before the basic app works
- Add workspace configurations before single-service works
- Change the directory structure before deploying successfully once

DO:
- Get the template deploying first (`saac deploy`, verify with `saac logs`)
- Add one feature, deploy, verify
- Add the next feature, deploy, verify

### Rule 5: .dockerignore should NOT exclude build outputs

```
# Good .dockerignore
node_modules
.git
.env
```

Do NOT add `dist/` or `build/` — those are generated INSIDE the container by `RUN npm run build`. The .dockerignore only affects what gets COPIED into the build context.

## Environment Variables

Env vars set via `saac env set KEY=VALUE` are written to `.env` in your repo directory before build. Reference them in docker-compose.yml:

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

Or use `env_file: .env` on your service.

## Two Containers Per App

Every app gets:
- **Production** (`yourapp.startanaicompany.com`) — immutable image, rebuilt on `saac deploy`
- **Hot-reload** (`yourapp-hot.startanaicompany.com`) — volume-mounted source, auto-updates on `git push`

## Debugging Commands

```bash
saac logs                              # Runtime logs
saac logs --type build                 # Build/deploy logs
saac exec "ls -la"                     # Run command in container
saac exec "cat package.json"           # Check what's actually in the container
saac db sql "SELECT * FROM users LIMIT 5"  # Query database
saac db containers                     # List database containers
```

## Common Mistakes and Fixes

| Mistake | Fix |
|---------|-----|
| `ports: "3000:3000"` | Change to `expose: ["3000"]` |
| `DB_HOST=localhost` | Change to `DB_HOST=postgres` (service name) |
| No Dockerfile | Create one (see Rule 3) |
| TypeScript not compiling | Add `RUN npm run build` in Dockerfile |
| `.dockerignore` has `dist/` | Remove it — dist is built inside container |
| `npm start` undefined | Add `"start": "node server.js"` to package.json scripts |
| Container exits immediately | Check `saac logs` — usually a missing env var or import error |
| "ECONNREFUSED 127.0.0.1" | You're using localhost — change to the Docker service name |

## Do NOT Add Traefik Labels

The SAAC daemon handles Traefik routing automatically via file provider. Traefik Docker labels in your docker-compose.yml are **ignored**. You can remove them.