# Sandbox Environments

## When to use

Use a sandbox when you need to:
- Run the full service stack (Docker services, probod, console)
- Test changes end-to-end with `make test-e2e`
- Build the full binary with `make build`
- Run any command that requires Docker or the full service stack

## Quick reference

```bash
# Create a sandbox (first time only)
make sandbox-create

# Start an existing sandbox
make sandbox-start

# Get the VM IP and service URLs
make sandbox-status

# Interactive shell
make sandbox-ssh

# Stop (shutdown — preserves disk and Docker images, but running processes are lost)
make sandbox-stop

# Delete entirely
make sandbox-delete
```

## Accessing services

After `make sandbox-status`, use the VM IP to access services from the host:

| Service            | URL                         |
| ------------------ | --------------------------- |
| Console            | `http://<vm-ip>:5173`       |
| Compliance Portal  | `http://<vm-ip>:5174`       |
| API                | `http://<vm-ip>:8080`       |
| Grafana    | `http://<vm-ip>:3001`       |
| Mailpit    | `http://<vm-ip>:8025`       |
| Keycloak   | `http://<vm-ip>:8082`       |
| PostgreSQL | `psql -h <vm-ip> -U probod` |

## Auto-generated configuration

During provisioning, the sandbox automatically generates:

- **`/etc/probod/config.yml`** — probod config with the VM IP as cookie domain, `secure: false`, and correct CORS origins
- **`apps/console/.env`** and **`apps/compliance-portal/.env`** — `VITE_API_URL` pointing to the VM IP

Probod config is at `/etc/probod/config.yml`.

### Custom environment variables

To inject developer-specific secrets (SSO, API keys, etc.) into the sandbox, create a `.sandbox.env` file at the repo root:

```bash
# .sandbox.env (gitignored — never committed)
AUTH_SAML_IDP_METADATA_URL=https://login.example.com/metadata
AUTH_OIDC_CLIENT_ID=my-client-id
AUTH_OIDC_CLIENT_SECRET=s3cret
```

This file is sourced during provisioning before `probod-bootstrap` runs. Any variable set here overrides the defaults. The sandbox must be recreated (`sandbox-delete` + `sandbox-create`) for changes to take effect.

## Systemd services

The sandbox provisions four systemd services:

| Service                    | Description                                                | Starts on boot |
| -------------------------- | ---------------------------------------------------------- | -------------- |
| `probo-stack`              | Docker Compose stack (Postgres, SeaweedFS, Keycloak, etc.) | Yes            |
| `probod`                   | Probo API server (depends on `probo-stack`)                | No             |
| `probo-console`            | Console frontend dev server                                | No             |
| `probo-compliance-portal`  | Compliance portal frontend dev server                     | No             |

`probo-stack` starts automatically when the VM boots. `probod`, `probo-console`, and `probo-compliance-portal` must be started manually after building.

Manage them with `systemctl`:
```bash
./contrib/lima/sandbox.sh exec -- sudo systemctl start probod probo-console probo-compliance-portal
./contrib/lima/sandbox.sh exec -- sudo systemctl stop probod
./contrib/lima/sandbox.sh exec -- sudo systemctl restart probod
./contrib/lima/sandbox.sh exec -- sudo systemctl status probod
./contrib/lima/sandbox.sh exec -- sudo journalctl -u probod -f
```

## Common workflows

**Run tests:**
```bash
./contrib/lima/sandbox.sh exec -- make test
```

**Run e2e tests:**
```bash
./contrib/lima/sandbox.sh exec -- make test-e2e
```