Requirements
This page lists what both self-hosted paths need: hardware, what Octopize gives you, what you prepare, and the network flows to open. What is specific to a path, such as Docker on the server or the cluster components for Kubernetes, is on that path's installation page.
Hardware
The same capacity is needed whether Avatar runs on one Docker server or across the nodes of a Kubernetes cluster:
| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 4 cores, x86_64, 2.30 GHz | More, for faster jobs |
| Memory | 32 GB | 64 GB |
| Disk | 100 GB | More for large datasets |
| Network | 100 MB/s | More for large datasets |
Provided by Octopize
- Registry credentials for
quay.io, which hosts the private Avatar images. You receive them when the contract is signed. - Telemetry credentials (an S3 bucket name, an access key ID and a secret), if you enable usage telemetry.
- SMTP credentials, if you choose to send email through Octopize's mail service (AWS SES) rather than your own server.
Prepared by you
- A domain name that points at the server or the load balancer, for example
avatar.company.com. Every public URL (web client, API, storage, SSO) is derived from it. - A TLS certificate for that domain, with its private key, in PEM format. The Docker
installation page explains how to convert a
.pfxbundle or generate a self-signed certificate for a test deployment. - An SMTP server that Avatar can send email through: host, port, credentials if needed, and the TLS mode (STARTTLS or implicit TLS). Email is required: users receive their account setup and password reset links by email. Raw IP addresses are not accepted as the SMTP host.
Network flows
Inbound
| Port | From | Used for |
|---|---|---|
| 443 | User browsers and clients | The web client, the API, single sign-on, and dataset upload and download (S3 endpoint) |
Outbound
| Destination | Port | When | Used for |
|---|---|---|---|
quay.io | 443 | Installation and upgrades | Avatar images (avatar-service-api, avatar-web), the Helm chart and the deploy tool image |
docker.io | 443 | Installation and upgrades | Supporting images (PostgreSQL, Nginx, SeaweedFS) |
ghcr.io | 443 | Installation and upgrades | Authentik images |
pypi.org | 443 | Installation and upgrades | The octopize-deploy-tool package (Docker path only) |
| Your SMTP server | 25, 465 or 587 | Always | Account setup, password reset and notification emails |
sentry.io | 443 | Optional | Error reporting |
license.octopize.io | 443 | Optional | Client compatibility mapping (download only) |
| The telemetry S3 endpoint | 443 | Optional | Usage telemetry, when enabled |
| Your source and target databases | Their own ports (5432, 3306, 1521, 1433, 8123…) | Optional, Kubernetes only | Database runs, from the database connector pod |
The installation and upgrade flows can be closed once the deployment is running. The optional flows can be turned off entirely, see Air-gapped deployments.
Container images
The back end is written in Python (dask, polars, pyarrow, pandas, numpy), and the web
client in Next.js with TypeScript. Sizes as of writing:
| Image | Registry | Size | Notes |
|---|---|---|---|
avatar-service-api | quay.io | 3.00 GB | Private |
avatar-web | quay.io | 0.30 GB | Private |
authentik | ghcr.io | 1.00 GB | |
postgres | docker.io | 0.40 GB | |
seaweedfs | docker.io | 0.20 GB | |
nginx | docker.io | 0.20 GB | Docker path only |
avatar-connector | quay.io | Private. Optional, Kubernetes only: the database connector |
Plan for about 6 GB of disk space per Avatar version, and prune old images after upgrades.
Air-gapped deployments
Avatar runs without internet access. Before installing:
- Mirror the container images to a registry the deployment can reach, or load them onto the server.
- Transfer the installer: the
octopize-deploy-toolpackage or its image for Docker, or the Helm chart archive (helm pull … --untar) for Kubernetes. - Have the TLS certificate available locally.
- Make sure an internal SMTP server is reachable.
Then turn off the optional outbound flows:
| Flow | Docker | Kubernetes |
|---|---|---|
| Error reporting (Sentry) | IS_SENTRY_ENABLED: false | api.config.sentry.enabled: false |
| Client compatibility mapping | COMPATIBILITY_MAPPING_URL: "disabled" | api.config.compatibilityMappingUrl: "disabled" |
| Usage telemetry | Leave the telemetry values empty | Leave the telemetry.s3 values empty |
On Docker, set these in your configuration file. On Kubernetes, see also pointing the chart at a mirror.
For mirroring the Authentik images, see the Authentik air-gapped documentation.