# Getting Started

## Prerequisites

- Docker and Docker Compose

## Running with Docker Compose

```bash
docker compose up --build
```

Open [http://localhost:3000](http://localhost:3000). Default credentials: `admin` / `admin`.

Data persists in the `sb_data` named volume. To reset everything:

```bash
docker compose down -v
```

## First Boot

On first start, Armature will:

1. Run database migrations (SQLite by default in compose).
2. Create the admin user from `ARMATURE_ADMIN_USERNAME` / `ARMATURE_ADMIN_PASSWORD` env vars.
3. Auto-install the curated default package set (notes, chat-core, dashboard, workflow demos, etc.).

No manual setup steps are required.

## Installing Additional Packages

The Docker image ships with extra packages beyond the default set. To install them:

- **Via Admin UI**: Go to `/admin` > Packages. Browse, enable, or install packages.
- **Via environment variable**: Set `BUNDLED_PACKAGES` before starting:

```bash
# Install all bundled packages
BUNDLED_PACKAGES="*" docker compose up --build

# Install specific extras
BUNDLED_PACKAGES="notes,tasks,schedules" docker compose up --build
```

You can also upload `.pkg` archives through the Admin > Packages page.

## Key URLs

| URL | Purpose |
|-----|---------|
| `/` | Redirects to your default surface |
| `/admin` | Admin panel (users, packages, settings, teams) |
| `/settings` | User settings (profile, preferences, default surface) |
| `/welcome` | Welcome page (shown when no surfaces are installed) |
| `/api/docs` | Interactive OpenAPI documentation |

## Key Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `8080` | Backend API port |
| `DB_DRIVER` | auto | `postgres` or `sqlite` |
| `DATABASE_URL` | | PostgreSQL DSN or SQLite file path |
| `JWT_SECRET` | `dev-secret-change-me` | **Change in production** |
| `ENCRYPTION_KEY` | | AES-256 key for credential encryption |
| `AUTH_MODE` | `builtin` | `builtin`, `mtls`, or `oidc` |
| `STORAGE_BACKEND` | auto | `pvc` or `s3` |
| `STORAGE_PATH` | `/data/storage` | PVC mount point |
| `ARMATURE_ADMIN_USERNAME` | | Bootstrap admin username |
| `ARMATURE_ADMIN_PASSWORD` | | Bootstrap admin password |
| `BUNDLED_PACKAGES` | (empty) | `""` = curated defaults, `"*"` = all, or comma-separated IDs |
| `SKIP_BUNDLED_PACKAGES` | `false` | Disable auto-install entirely |
| `LOG_LEVEL` | `info` | `debug`, `info`, `warn`, `error` |
| `LOG_FORMAT` | `text` | `text` or `json` |

## From Source

```bash
git clone <repo-url> && cd armature
cp server/.env.example server/.env   # edit DB credentials
cd server && go run .
# Backend on http://localhost:8080
```

## Next Steps

- [Extension Guide](EXTENSION-GUIDE.md) -- Author your own packages
- [API Reference](API-REFERENCE.md) -- REST API overview
- [Deployment](DEPLOYMENT.md) -- Production deployment
- [Architecture](ARCHITECTURE.md) -- System design