26595b724f
Embed and build @probo/compliance-portal for the /trust path and custom-domain SPA so production ships the v2 portal. Keep apps/trust in the repo for local use on port 5175; portal takes 5174. Signed-off-by: Émile Ré <emile@probo.com>
102 lines
3.5 KiB
Markdown
102 lines
3.5 KiB
Markdown
# 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
|
|
```
|