Depotex is two programs, the server (API, package-manager endpoints, background jobs) and the web app, in front of PostgreSQL, optional Redis and artifact storage. Decide these before installing: they're the parts that are hard to change later.
1. Components
| Part | Role | Notes |
|---|---|---|
| Server | Every API and package-manager request, scheduled jobs, events, plugins | Port 8080. Stateless apart from a small per-server data folder (below). Several servers form a cluster |
| Web app | The pages people use; forwards /api and package-manager traffic to the server | Port 3000. Stateless; run two or more for availability |
| PostgreSQL | Every record: users, settings (encrypted), repositories, versions, events, the audit log | Required. The single source of truth |
| Redis | Coordination between servers: rate limits, live updates, locks | Optional on one server, required for a cluster. Losing it is survivable: see Single Node & Cluster |
| Artifact storage | The files of every artifact | Local disk, S3 (or S3-compatible), MinIO or Azure Blob |
| Reverse proxy / ingress | TLS, the public address, /api/ws to the server | Any proxy or load balancer; examples for Caddy and nginx in Install Depotex |
2. Single server or cluster
| Single server | Cluster | |
|---|---|---|
| License | Standard or higher | Pro or higher, with enough servers |
| Redis | Optional | Required (one server, Sentinel or Redis Cluster) |
| Storage | Any | Shared by every server: S3, MinIO, Azure, or one volume mounted at the same path everywhere |
| Availability | Downtime for restarts and upgrades | Rolling upgrades; a failed server's work is taken over |
Every feature behaves the same either way. Start with one server if you're unsure: going to a cluster later means adding Redis and shared storage, not reinstalling.
3. PostgreSQL
- A supported PostgreSQL release, 15 or later (the Helm chart's built-in database is 17; the server image's backup tools are 18 and work with 18 and older). Managed services (Amazon RDS and Aurora PostgreSQL, Google Cloud SQL, Azure Database for PostgreSQL) work.
- One database for Depotex, owned by the role Depotex connects as. The role needs CREATEROLE if plugins use databases, and must not be a superuser.
- Connections: each server opens up to pool_max_conns (default 4, or the number of CPUs if more). Keep servers × pool_max_conns plus room for maintenance under max_connections. See Database connections.
- Use TLS (sslmode=verify-full) when the database isn't on the same host, and back the database up with your platform's tools as well as with Depotex backups.
4. Storage
- Size it for your artifacts plus growth: proxies keep copies of everything fetched, Docker images are large. Cleanup policies and quotas keep it in check (see Spaces).
- Object storage (S3, MinIO, Azure) is the usual choice and the only one that needs nothing extra for a cluster. On AWS the server can use its IAM role instead of keys.
- Each server also has a small data folder of its own (/app/data in the image): the encrypted bootstrap file, its search index (rebuilt when missing) and its log files. Give it persistent disk, about 10 GiB to start; the search index grows with the number of versions.
- Backups and scans need temporary space: a compressed database dump for backups (BACKUP_TEMP_DIR), the largest unpacked image for image scans (IMAGE_SCAN_TMP_DIR).
5. Sizing
Starting points, to be adjusted from what monitoring and the system check show under your load:
| Installation | Servers | Web app | PostgreSQL | Redis |
|---|---|---|---|---|
| Evaluation, small team | 1 × 1 CPU, 1–2 GiB | 1 × 0.5 CPU, 512 MiB | 1–2 CPU, 2 GiB, 20 GiB disk | none |
| Department, CI on every commit | 1–2 × 2 CPU, 4 GiB | 2 × 1 CPU, 1 GiB | 2–4 CPU, 8 GiB, SSD | small (256 MiB) |
| Company-wide, high availability | 3+ × 4 CPU, 8 GiB | 2–3 × 1 CPU, 1 GiB | 8+ CPU, 32 GiB, replicated | replicated, 1 GiB |
- Most load is package-manager traffic from CI: count builds per hour and dependencies per build, not people.
- Small files are database-bound: a faster database (and pool_max_conns to match) helps more than more servers. Large files are network- and storage-bound.
- Image scans (Syft) and SBOM inspection run one at a time per cluster in the background; they use CPU and temporary disk on the server that runs them.
6. Network
| From | To | Port | Why |
|---|---|---|---|
| Users, CI | Reverse proxy | 443 | Web app, API and package managers, on one host name |
| Reverse proxy | Web app | 3000 | Everything except /api/ws |
| Reverse proxy | Server | 8080 | /api/ws (live updates, WebSocket) |
| Web app | Server | 8080 | API and package traffic |
| Server | PostgreSQL, Redis, storage | 5432, 6379, 443/9000 | Its records, coordination and files |
| Servers | Each other | none | Servers coordinate through PostgreSQL and Redis only |
| Prometheus | Server | 9090 (optional) | Metrics, never through the public address |
Outbound from the server, only for what you use: upstream registries for proxy repositories, identity providers (single sign-on, Entra ID, Google), SMTP or Amazon SES, webhook targets, OSV vulnerability data (or upload it offline in Settings → Vulnerability data), and plugins' declared hosts. An outbound HTTP proxy and private certificate authorities are set in Settings → Repositories. Nothing is sent to Vectored, apart from the installation ID when the vibe artifacts package list is downloaded.
7. Address and TLS
- Give Depotex its own host name (https://depotex.example.com); it can't be served under a path.
- Terminate TLS at your proxy or ingress. Package managers and single sign-on require HTTPS in practice.
- Set TRUSTED_PROXIES (backend.trustedProxies in Helm) to the proxies in front, or every request seems to come from the proxy.
- Allow large request bodies and long timeouts at the proxy for big uploads and downloads.
8. Before you install
- PostgreSQL database and role created; Redis ready if you run a cluster; bucket or container created.
- DNS name and TLS certificate.
- A place to keep secrets: CONFIG_ENCRYPTION_KEY, the first administrator's password, the setup and recovery keys.
- Who will request the license, and with which tier, user and server counts (see Licensing).
- Email (SMTP or Amazon SES) for invitations and password resets.
- Your identity source: local accounts, LDAP or Active Directory, Entra ID, Google Workspace, SCIM, and single sign-on.