ArchiveBox Helm Chart
Deploy ArchiveBox on Kubernetes using the official archivebox/archivebox container image.
ArchiveBox is a self-hosted web archiving platform that captures websites in multiple formats, including HTML, PDF, PNG, WARC, and media, using Chromium headless.
Features
- Multi-format archiving - HTML, PDF, screenshot, WARC, media extraction
- Chromium headless - full page rendering with
/dev/shmtmpfs - SQLite or PostgreSQL - embedded SQLite is the default; external PostgreSQL is also supported
- Persistent storage - archived content and SQLite database on PVC, can also be configured to use remote Postgres
- Admin credentials - managed via Kubernetes Secret
- Ingress support - TLS with cert-manager
- S3-compatible backups - optional CronJob for
/dataarchives
Installation
HTTPS repository:
helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install archivebox helmforge/archivebox -f values.yaml
OCI registry:
helm install archivebox oci://ghcr.io/helmforgedev/helm/archivebox -f values.yaml
Basic Example
# values.yaml
archivebox:
adminUsername: admin
adminPassword: "your-secure-password"
After deploying:
kubectl port-forward svc/<release>-archivebox 5797:80
# Open http://localhost:5797/
Architecture Guides
One Recreate Deployment owns the /data dataset: SQLite, indexes,
configuration, and captured artifacts. The optional backup CronJob reads that
same claim and uploads a volume archive to S3-compatible storage. The chart
deploys one ArchiveBox replica.
The chart owns Kubernetes workload, storage, routing, credentials, and optional backup resources. TLS policy, capture-egress controls, malicious-content isolation, storage lifecycle, off-cluster retention, and monitoring remain platform responsibilities. See DESIGN.md for the Mermaid topology, security and observability boundaries, gaps, and explicit non-goals.
Examples
Using an Existing Secret
archivebox:
existingSecret: my-archivebox-secret
existingSecretUsernameKey: admin-username
existingSecretPasswordKey: admin-password
Values & Configuration Reference
All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.
|-----|---------|-------------|
| archivebox.port | 5797 | Application port |
| archivebox.adminUsername | admin | Admin username |
| archivebox.adminPassword | "" | Admin password (auto-generated if empty) |
| archivebox.allowedHosts | * | Allowed hostnames |
| archivebox.publicIndex | True | Public index page |
| archivebox.publicAddLinks | False | Public add URL view (PUBLIC_ADD_VIEW) |
| archivebox.baseUrl | "" | BASE_URL environment variable; empty uses configuration from the admin UI |
| archivebox.serverSecurityMode | auto | Server security mode |
| archivebox.puid / archivebox.pgid | "" | Optional UID/GID overrides; otherwise autodetected |
| archivebox.mediaMaxSize | 750m | Max media download size |
| archivebox.timeout | 60 | URL archiving timeout (seconds) |
| externalDatabase.enabled | false | Use external PostgreSQL |
| externalDatabase.existingSecret | "" | Secret containing the PostgreSQL password |
| persistence.enabled | true | Enable persistence for /data |
| persistence.size | 50Gi | PVC size (plan for large archives) |
| ingress.enabled | false | Enable ingress |
| service.port | 80 | Service port |
| backup.enabled | false | Enable scheduled S3-compatible backup |
| backup.schedule | 0 3 * * * | Backup CronJob schedule |
| backup.s3.credentialsFromPodIdentity | false | Use EKS Pod Identity or IRSA instead of static S3 keys |
Public URL
Configure BASE_URL through the first-use admin UI. To set it through Helm,
set archivebox.baseUrl to the public URL, such as https://archive.example.com.
BASE_URL configures links, CSRF origins, and HTTPS handling.
With archivebox.serverSecurityMode: auto, raw archived HTML uses no-JS replay
on public hostnames. For full JavaScript replay on separate subdomains, use
safe-subdomains-fullreplay with wildcard DNS and ingress, plus a wildcard
certificate for HTTPS. See the upstream security modes.
External PostgreSQL
SQLite is the default database. To use an existing PostgreSQL database:
externalDatabase:
enabled: true
host: postgres.database.svc.cluster.local
name: archivebox
user: archivebox
existingSecret: archivebox-postgres
existingSecretPasswordKey: database-password
Create the database, role, and password Secret first. /data stores archived
files and configuration.
For existing collections, migrate SQLite records to PostgreSQL before changing
the backend.
Upgrading
- Remove
archivebox.publicSnapshots; manage snapshot permissions in the UI. If it was"False", preserve private capture defaults througharchivebox.extraEnvwithname: PERMISSIONSandvalue: private. - Review saved security contexts and remove fixed UID/GID overrides to use autodetection. Migrate removed keys before reusing saved values, preserving existing Secret and PVC references.
Security Scan
The upstream entrypoint starts as root, prepares writable paths, then runs
ArchiveBox as non-root. It detects the existing collection owner unless
archivebox.puid / archivebox.pgid are set, falling back to 911 for a new
root-owned collection. It retains CHOWN, DAC_OVERRIDE, FOWNER, SETUID, and SETGID
for startup.
The chart also includes a bounded init container that changes only the /data
directory itself when its current owner is root. It never recursively rewrites
an existing collection. The application container still starts as root because
the upstream entrypoint discovers the collection owner and drops privileges at
runtime. Consequently, the default workload is not compatible with a namespace
that enforces the Kubernetes Pod Security restricted profile without an
explicit policy exception for this Deployment.
Security Scan:
Kubescape scan for MITRE,NSA,SOC2 with the default values:
| Framework | Score |
|---|---|
| MITRE | 100.00% |
| NSA | 70.00% |
| SOC2 | 80.00% |
| Aggregate resource score | 78.79% |
Expected follow-up hardening is operator-dependent:
- Set explicit CPU and memory requests and limits for the ArchiveBox workload.
- Add namespace-level NetworkPolicy where the platform requires restricted ingress and egress.
- Use an existing Secret for admin and S3 credentials in production.
Limitations
- Single instance only - horizontal scaling is not supported, including with PostgreSQL
- Storage-heavy - each archived snapshot is commonly 2-50MB; plan PVC size accordingly
- Chromium resources - requires at least 2Gi RAM for Chromium headless rendering
/dev/shm- automatically mounted as memory-backed tmpfs for Chromium
Troubleshooting
- If startup remains incomplete, inspect application logs, confirm data and runtime paths are writable by the selected UID/GID, and allow enough time for migrations on a large archive.
- If captures fail, check Chromium memory pressure, DNS and outbound network policy, the target site's behavior, and per-URL timeout settings.
- If the UI rejects the public hostname, align
archivebox.baseUrlwith the Ingress host and TLS name. - If backup Jobs fail, inspect both containers, verify the S3 endpoint and Secret keys, and test restore of the full archive before relying on retention.
- The scheduled backup archives live
/dataand never dumps external PostgreSQL. Use a quiesced maintenance window and retain a matching database dump as described in the backup guide.
More Information
System Architecture
DESIGN.md SyncedVerified architecture contract rendered dynamically from GitHub DESIGN.md
flowchart LR user[Administrator or reader] --> edge[Ingress optional] edge --> service[ArchiveBox Service] service --> app[Single ArchiveBox Deployment] admin[Admin Secret] --> app app --> data[(ArchiveBox data PVC)] app --> web[Websites and capture dependencies] app -.-> postgres[(External PostgreSQL optional)] data --> cron[Backup CronJob optional] cron --> s3[S3-compatible object storage] s3secret[S3 Secret] --> cron backupidentity[Backup workload identity optional] --> cron
Archivebox Values Schema Reference
Official schema parameters, default values, and types extracted directly from the chart repository.
Global(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| global | object | - | Global settings shared by the chart. |
Name Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nameOverride | string | "" | Chart configuration parameter |
Fullname Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| fullnameOverride | string | "" | Chart configuration parameter |
Common Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| commonLabels | object | - | Chart configuration parameter |
Common Annotations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| commonAnnotations | object | - | Chart configuration parameter |
Image(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| image.repository | string | docker.io/archivebox/archivebox | Chart configuration parameter |
| image.tag | string | "" | Chart configuration parameter |
| image.pullPolicy | string | IfNotPresent | Chart configuration parameter Allowed: AlwaysIfNotPresentNever |
Image Pull Secrets(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| imagePullSecrets | array | - | Chart configuration parameter |
Archivebox(17)
| Parameter | Type | Default | Description |
|---|---|---|---|
| archivebox.port | integer | 5797 | Application port |
| archivebox.adminUsername | string | admin | Admin username |
| archivebox.adminPassword | string | "" | Admin password |
| archivebox.existingSecret | string | "" | Existing secret containing admin credentials |
| archivebox.existingSecretUsernameKey | string | admin-username | Chart configuration parameter |
| archivebox.existingSecretPasswordKey | string | admin-password | Chart configuration parameter |
| archivebox.allowedHosts | string | * | Allowed hostnames |
| archivebox.publicIndex | string | True | Allow public index access |
| archivebox.publicAddLinks | string | False | Allow public access to the add URL view (PUBLIC_ADD_VIEW) |
| archivebox.mediaMaxSize | string | 750m | Maximum media file size |
| archivebox.timeout | string | 60 | Archiving timeout in seconds |
| archivebox.timezone | string | UTC | Timezone |
| archivebox.extraEnv | array | - | Chart configuration parameter |
| archivebox.baseUrl | string | "" | BASE_URL environment variable; empty uses configuration from the admin UI |
| archivebox.serverSecurityMode | string | auto | Server security mode Allowed: autosafe-subdomains-fullreplaysafe-onedomain-nojsreplayunsafe-onedomain-noadmindanger-onedomain-fullreplay |
| archivebox.puid | string | "" | Non-root application UID; empty detects existing collection owner |
| archivebox.pgid | string | "" | Application GID; empty detects existing collection owner |
External Database(7)
| Parameter | Type | Default | Description |
|---|---|---|---|
| externalDatabase.enabled | boolean | false | Chart configuration parameter |
| externalDatabase.host | string | "" | Chart configuration parameter |
| externalDatabase.port | integer | 5432 | Chart configuration parameter |
| externalDatabase.name | string | archivebox | Chart configuration parameter |
| externalDatabase.user | string | archivebox | Chart configuration parameter |
| externalDatabase.existingSecret | string | "" | Existing Secret containing the PostgreSQL password |
| externalDatabase.existingSecretPasswordKey | string | database-password | Chart configuration parameter |
Persistence(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| persistence.enabled | boolean | true | Chart configuration parameter |
| persistence.size | string | 50Gi | Chart configuration parameter |
| persistence.storageClass | string | "" | Chart configuration parameter |
| persistence.accessModes | array | - | Chart configuration parameter |
| persistence.existingClaim | string | "" | Chart configuration parameter |
Service Account(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| serviceAccount.create | boolean | false | Chart configuration parameter |
| serviceAccount.name | string | "" | Chart configuration parameter |
| serviceAccount.annotations | object | - | Chart configuration parameter |
Service & Networking(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| service.type | string | ClusterIP | Chart configuration parameter Allowed: ClusterIPNodePortLoadBalancer |
| service.port | integer | 80 | Chart configuration parameter |
| service.annotations | object | - | Chart configuration parameter |
Ingress(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| ingress.enabled | boolean | false | Chart configuration parameter |
| ingress.ingressClassName | string | traefik | Chart configuration parameter |
| ingress.annotations | object | - | Chart configuration parameter |
| ingress.hosts | array | - | Chart configuration parameter |
| ingress.tls | array | - | Chart configuration parameter |
Health Probes(18)
| Parameter | Type | Default | Description |
|---|---|---|---|
| probes.startup.enabled | boolean | - | Chart configuration parameter |
| probes.startup.path | string | - | Chart configuration parameter |
| probes.startup.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.startup.periodSeconds | integer | - | Chart configuration parameter |
| probes.startup.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.startup.failureThreshold | integer | - | Chart configuration parameter |
| probes.liveness.enabled | boolean | - | Chart configuration parameter |
| probes.liveness.path | string | - | Chart configuration parameter |
| probes.liveness.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.liveness.periodSeconds | integer | - | Chart configuration parameter |
| probes.liveness.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.liveness.failureThreshold | integer | - | Chart configuration parameter |
| probes.readiness.enabled | boolean | - | Chart configuration parameter |
| probes.readiness.path | string | - | Chart configuration parameter |
| probes.readiness.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.readiness.periodSeconds | integer | - | Chart configuration parameter |
| probes.readiness.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.readiness.failureThreshold | integer | - | Chart configuration parameter |
Resources(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| resources | object | - | Chart configuration parameter |
Pod Security(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podSecurityContext.fsGroup | integer | - | Chart configuration parameter |
| podSecurityContext.fsGroupChangePolicy | string | - | Chart configuration parameter Allowed: AlwaysOnRootMismatch |
| podSecurityContext.seccompProfile.type | string | - | Chart configuration parameter Allowed: RuntimeDefaultUnconfinedLocalhost |
Container Security(7)
| Parameter | Type | Default | Description |
|---|---|---|---|
| securityContext.runAsUser | integer | - | Chart configuration parameter |
| securityContext.runAsGroup | integer | - | Chart configuration parameter |
| securityContext.runAsNonRoot | boolean | - | Chart configuration parameter |
| securityContext.allowPrivilegeEscalation | boolean | - | Chart configuration parameter |
| securityContext.capabilities.drop | array | - | Chart configuration parameter |
| securityContext.capabilities.add | array | - | Chart configuration parameter |
| securityContext.seccompProfile.type | string | - | Chart configuration parameter Allowed: RuntimeDefaultUnconfinedLocalhost |
Node Selector(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nodeSelector | object | - | Chart configuration parameter |
Tolerations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| tolerations | array | - | Chart configuration parameter |
Affinity(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| affinity | object | - | Chart configuration parameter |
Topology Spread Constraints(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| topologySpreadConstraints | array | - | Chart configuration parameter |
Priority Class Name(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| priorityClassName | string | "" | Chart configuration parameter |
Termination Grace Period Seconds(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| terminationGracePeriodSeconds | integer | 30 | Chart configuration parameter |
Pod Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podLabels | object | - | Chart configuration parameter |
Pod Annotations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podAnnotations | object | - | Chart configuration parameter |
Extra Volumes(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumes | array | - | Chart configuration parameter |
Extra Volume Mounts(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumeMounts | array | - | Chart configuration parameter |
Backup(29)
| Parameter | Type | Default | Description |
|---|---|---|---|
| backup.enabled | boolean | false | Enable scheduled backups |
| backup.schedule | string | 0 3 * * * | Cron schedule for backups |
| backup.suspend | boolean | false | Suspend the CronJob |
| backup.archivePrefix | string | archivebox | Prefix for backup archive filenames |
| backup.concurrencyPolicy | string | - | Chart configuration parameter Allowed: AllowForbidReplace |
| backup.successfulJobsHistoryLimit | integer | - | Chart configuration parameter |
| backup.failedJobsHistoryLimit | integer | - | Chart configuration parameter |
| backup.backoffLimit | integer | - | Chart configuration parameter |
| backup.images.tar | string | - | Chart configuration parameter |
| backup.images.uploader | string | - | Chart configuration parameter |
| backup.resources | object | - | CPU and memory for backup containers |
| backup.podSecurityContext | object | - | Chart configuration parameter |
| backup.archiverSecurityContext | object | - | Chart configuration parameter |
| backup.securityContext | object | - | Chart configuration parameter |
| backup.serviceAccount.create | boolean | true | Chart configuration parameter |
| backup.serviceAccount.name | string | "" | Chart configuration parameter |
| backup.serviceAccount.annotations | object | - | Chart configuration parameter |
| backup.serviceAccount.automountServiceAccountToken | boolean | false | Chart configuration parameter |
| backup.s3.endpoint | string | - | Chart configuration parameter |
| backup.s3.bucket | string | - | Chart configuration parameter |
| backup.s3.prefix | string | - | Chart configuration parameter |
| backup.s3.createBucketIfNotExists | boolean | - | Chart configuration parameter |
| backup.s3.existingSecret | string | - | Chart configuration parameter |
| backup.s3.existingSecretAccessKeyKey | string | - | Chart configuration parameter |
| backup.s3.existingSecretSecretKeyKey | string | - | Chart configuration parameter |
| backup.s3.accessKey | string | - | Chart configuration parameter |
| backup.s3.secretKey | string | - | Chart configuration parameter |
| backup.s3.region | string | - | Chart configuration parameter |
| backup.s3.credentialsFromPodIdentity | boolean | false | Chart configuration parameter |
Extra Manifests(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraManifests | array | - | Chart configuration parameter |
No schema parameters match your search
Try searching for a different keyword or reset the filter.