Skip to content
Archivebox icon
v2.0.0App: v0.9.77Pinned DigestS3 Backup Ready

Production Helm chart • Apache-2.0 • Zero-Root • Verified on Kubernetes v1.33-v1.36+

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/shm tmpfs
  • 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 /data archives

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
Official Schema

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.

View Values Schema

|-----|---------|-------------| | 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 through archivebox.extraEnv with name: PERMISSIONS and value: 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.baseUrl with 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 /data and 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 Synced

Verified 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
Official Contractvalues.schema.json

Archivebox Values Schema Reference

Official schema parameters, default values, and types extracted directly from the chart repository.

118 parametersValues Studio

Global(1)

ParameterTypeDefaultDescription
globalobject-Global settings shared by the chart.

Name Override(1)

ParameterTypeDefaultDescription
nameOverridestring""Chart configuration parameter

Fullname Override(1)

ParameterTypeDefaultDescription
fullnameOverridestring""Chart configuration parameter

Common Labels(1)

ParameterTypeDefaultDescription
commonLabelsobject-Chart configuration parameter

Common Annotations(1)

ParameterTypeDefaultDescription
commonAnnotationsobject-Chart configuration parameter

Image(3)

ParameterTypeDefaultDescription
image.repositorystringdocker.io/archivebox/archiveboxChart configuration parameter
image.tagstring""Chart configuration parameter
image.pullPolicystringIfNotPresentChart configuration parameter
Allowed:AlwaysIfNotPresentNever

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Chart configuration parameter

Archivebox(17)

ParameterTypeDefaultDescription
archivebox.portinteger5797Application port
archivebox.adminUsernamestringadminAdmin username
archivebox.adminPasswordstring""Admin password
archivebox.existingSecretstring""Existing secret containing admin credentials
archivebox.existingSecretUsernameKeystringadmin-usernameChart configuration parameter
archivebox.existingSecretPasswordKeystringadmin-passwordChart configuration parameter
archivebox.allowedHostsstring*Allowed hostnames
archivebox.publicIndexstringTrueAllow public index access
archivebox.publicAddLinksstringFalseAllow public access to the add URL view (PUBLIC_ADD_VIEW)
archivebox.mediaMaxSizestring750mMaximum media file size
archivebox.timeoutstring60Archiving timeout in seconds
archivebox.timezonestringUTCTimezone
archivebox.extraEnvarray-Chart configuration parameter
archivebox.baseUrlstring""BASE_URL environment variable; empty uses configuration from the admin UI
archivebox.serverSecurityModestringautoServer security mode
Allowed:autosafe-subdomains-fullreplaysafe-onedomain-nojsreplayunsafe-onedomain-noadmindanger-onedomain-fullreplay
archivebox.puidstring""Non-root application UID; empty detects existing collection owner
archivebox.pgidstring""Application GID; empty detects existing collection owner

External Database(7)

ParameterTypeDefaultDescription
externalDatabase.enabledbooleanfalseChart configuration parameter
externalDatabase.hoststring""Chart configuration parameter
externalDatabase.portinteger5432Chart configuration parameter
externalDatabase.namestringarchiveboxChart configuration parameter
externalDatabase.userstringarchiveboxChart configuration parameter
externalDatabase.existingSecretstring""Existing Secret containing the PostgreSQL password
externalDatabase.existingSecretPasswordKeystringdatabase-passwordChart configuration parameter

Persistence(5)

ParameterTypeDefaultDescription
persistence.enabledbooleantrueChart configuration parameter
persistence.sizestring50GiChart configuration parameter
persistence.storageClassstring""Chart configuration parameter
persistence.accessModesarray-Chart configuration parameter
persistence.existingClaimstring""Chart configuration parameter

Service Account(3)

ParameterTypeDefaultDescription
serviceAccount.createbooleanfalseChart configuration parameter
serviceAccount.namestring""Chart configuration parameter
serviceAccount.annotationsobject-Chart configuration parameter

Service & Networking(3)

ParameterTypeDefaultDescription
service.typestringClusterIPChart configuration parameter
Allowed:ClusterIPNodePortLoadBalancer
service.portinteger80Chart configuration parameter
service.annotationsobject-Chart configuration parameter

Ingress(5)

ParameterTypeDefaultDescription
ingress.enabledbooleanfalseChart configuration parameter
ingress.ingressClassNamestringtraefikChart configuration parameter
ingress.annotationsobject-Chart configuration parameter
ingress.hostsarray-Chart configuration parameter
ingress.tlsarray-Chart configuration parameter

Health Probes(18)

ParameterTypeDefaultDescription
probes.startup.enabledboolean-Chart configuration parameter
probes.startup.pathstring-Chart configuration parameter
probes.startup.initialDelaySecondsinteger-Chart configuration parameter
probes.startup.periodSecondsinteger-Chart configuration parameter
probes.startup.timeoutSecondsinteger-Chart configuration parameter
probes.startup.failureThresholdinteger-Chart configuration parameter
probes.liveness.enabledboolean-Chart configuration parameter
probes.liveness.pathstring-Chart configuration parameter
probes.liveness.initialDelaySecondsinteger-Chart configuration parameter
probes.liveness.periodSecondsinteger-Chart configuration parameter
probes.liveness.timeoutSecondsinteger-Chart configuration parameter
probes.liveness.failureThresholdinteger-Chart configuration parameter
probes.readiness.enabledboolean-Chart configuration parameter
probes.readiness.pathstring-Chart configuration parameter
probes.readiness.initialDelaySecondsinteger-Chart configuration parameter
probes.readiness.periodSecondsinteger-Chart configuration parameter
probes.readiness.timeoutSecondsinteger-Chart configuration parameter
probes.readiness.failureThresholdinteger-Chart configuration parameter

Resources(1)

ParameterTypeDefaultDescription
resourcesobject-Chart configuration parameter

Pod Security(3)

ParameterTypeDefaultDescription
podSecurityContext.fsGroupinteger-Chart configuration parameter
podSecurityContext.fsGroupChangePolicystring-Chart configuration parameter
Allowed:AlwaysOnRootMismatch
podSecurityContext.seccompProfile.typestring-Chart configuration parameter
Allowed:RuntimeDefaultUnconfinedLocalhost

Container Security(7)

ParameterTypeDefaultDescription
securityContext.runAsUserinteger-Chart configuration parameter
securityContext.runAsGroupinteger-Chart configuration parameter
securityContext.runAsNonRootboolean-Chart configuration parameter
securityContext.allowPrivilegeEscalationboolean-Chart configuration parameter
securityContext.capabilities.droparray-Chart configuration parameter
securityContext.capabilities.addarray-Chart configuration parameter
securityContext.seccompProfile.typestring-Chart configuration parameter
Allowed:RuntimeDefaultUnconfinedLocalhost

Node Selector(1)

ParameterTypeDefaultDescription
nodeSelectorobject-Chart configuration parameter

Tolerations(1)

ParameterTypeDefaultDescription
tolerationsarray-Chart configuration parameter

Affinity(1)

ParameterTypeDefaultDescription
affinityobject-Chart configuration parameter

Topology Spread Constraints(1)

ParameterTypeDefaultDescription
topologySpreadConstraintsarray-Chart configuration parameter

Priority Class Name(1)

ParameterTypeDefaultDescription
priorityClassNamestring""Chart configuration parameter

Termination Grace Period Seconds(1)

ParameterTypeDefaultDescription
terminationGracePeriodSecondsinteger30Chart configuration parameter

Pod Labels(1)

ParameterTypeDefaultDescription
podLabelsobject-Chart configuration parameter

Pod Annotations(1)

ParameterTypeDefaultDescription
podAnnotationsobject-Chart configuration parameter

Extra Volumes(1)

ParameterTypeDefaultDescription
extraVolumesarray-Chart configuration parameter

Extra Volume Mounts(1)

ParameterTypeDefaultDescription
extraVolumeMountsarray-Chart configuration parameter

Backup(29)

ParameterTypeDefaultDescription
backup.enabledbooleanfalseEnable scheduled backups
backup.schedulestring0 3 * * *Cron schedule for backups
backup.suspendbooleanfalseSuspend the CronJob
backup.archivePrefixstringarchiveboxPrefix for backup archive filenames
backup.concurrencyPolicystring-Chart configuration parameter
Allowed:AllowForbidReplace
backup.successfulJobsHistoryLimitinteger-Chart configuration parameter
backup.failedJobsHistoryLimitinteger-Chart configuration parameter
backup.backoffLimitinteger-Chart configuration parameter
backup.images.tarstring-Chart configuration parameter
backup.images.uploaderstring-Chart configuration parameter
backup.resourcesobject-CPU and memory for backup containers
backup.podSecurityContextobject-Chart configuration parameter
backup.archiverSecurityContextobject-Chart configuration parameter
backup.securityContextobject-Chart configuration parameter
backup.serviceAccount.createbooleantrueChart configuration parameter
backup.serviceAccount.namestring""Chart configuration parameter
backup.serviceAccount.annotationsobject-Chart configuration parameter
backup.serviceAccount.automountServiceAccountTokenbooleanfalseChart configuration parameter
backup.s3.endpointstring-Chart configuration parameter
backup.s3.bucketstring-Chart configuration parameter
backup.s3.prefixstring-Chart configuration parameter
backup.s3.createBucketIfNotExistsboolean-Chart configuration parameter
backup.s3.existingSecretstring-Chart configuration parameter
backup.s3.existingSecretAccessKeyKeystring-Chart configuration parameter
backup.s3.existingSecretSecretKeyKeystring-Chart configuration parameter
backup.s3.accessKeystring-Chart configuration parameter
backup.s3.secretKeystring-Chart configuration parameter
backup.s3.regionstring-Chart configuration parameter
backup.s3.credentialsFromPodIdentitybooleanfalseChart configuration parameter

Extra Manifests(1)

ParameterTypeDefaultDescription
extraManifestsarray-Chart configuration parameter