Skip to content

Kubernetes

deploy/kubernetes/ in the source repository holds two Kustomize setups, each complete on its own, which kubectl applies as they are, no Helm:

  • app/, to run Artbucket for real: a namespace, a Deployment, a Service, and a Gateway with its HTTPRoutes (Gateway API, which replaces Ingress). Bring Postgres 16 or later and S3-compatible storage: managed ones (RDS, Cloud SQL, Neon; S3, R2, B2), or in the cluster (CloudNativePG, SeaweedFS, Garage). See Install.
  • quickstart/, for local development and trying the app: the same app with Postgres and storage beside it, and no Gateway. See Try it.

Without Kubernetes at all, Docker Compose is quicker still.

deploy/kubernetes/quickstart/ runs the app with its own Postgres and SeaweedFS beside it, and no Gateway, domain or certificate: you reach it through kubectl port-forward, and the cluster needs no Gateway API. Any cluster will do (kind, k3d, minikube, Docker Desktop), as long as it has a default storage class for its two volumes.

Terminal window
git clone https://github.com/pwnera/artbucket.git
cd artbucket
kubectl apply -k deploy/kubernetes/quickstart
kubectl -n artbucket rollout status deployment/artbucket

Then, each in a terminal of its own:

Terminal window
kubectl -n artbucket port-forward svc/artbucket 3000:80
Terminal window
kubectl -n artbucket port-forward svc/s3 9000:9000

Open http://localhost:3000 and make the first account. The second port-forward is where browsers upload: files go from the browser straight to storage, not through the app.

Its passwords and BETTER_AUTH_SECRET are written in quickstart/kustomization.yaml, so keep it to local development and trying the app. When you are done:

Terminal window
kubectl delete -k deploy/kubernetes/quickstart

That deletes the namespace, its volumes and everything in them. The rest of this page sets up the real thing, with app/.

The cluster needs the Gateway API CRDs (v1.0 or later) and a controller that implements them: Envoy Gateway, Istio, Cilium, Traefik, NGINX Gateway Fabric, or your cloud’s own. Most install the CRDs with them; otherwise:

Terminal window
kubectl apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.3.0/standard-install.yaml
Terminal window
git clone https://github.com/pwnera/artbucket.git
cd artbucket/deploy/kubernetes/app
cp secret.env.example secret.env # git ignores it

config.env holds the plain settings and becomes a ConfigMap:

Terminal window
APP_URL=https://assets.example.com
INTERNAL_URL=http://localhost:3000
HOSTNAME=0.0.0.0
S3_ENDPOINT=https://s3.eu-central-1.amazonaws.com
S3_REGION=eu-central-1
S3_BUCKET=acme-assets
S3_FORCE_PATH_STYLE=false
TRUSTED_PROXIES=private

Keep HOSTNAME=0.0.0.0: Kubernetes sets HOSTNAME to the pod’s name, and the server would listen on that address only. When the pod reaches storage inside the cluster, set S3_PUBLIC_ENDPOINT to where browsers upload.

secret.env becomes a Secret:

Terminal window
DATABASE_URL=postgres://artbucket:...@postgres.example.com:5432/artbucket
S3_ACCESS_KEY_ID=...
S3_SECRET_ACCESS_KEY=...
BETTER_AUTH_SECRET= # openssl rand -base64 32

Keep BETTER_AUTH_SECRET somewhere safe: a new one signs everyone out and makes stored secrets unreadable. Both objects’ names carry a hash of their contents, so a change to either rolls the pods.

Every variable is in Environment.

In gateway.yaml, set your domain (the one in APP_URL) in the Gateway’s listeners and both routes’ hostnames, your controller’s gatewayClassName (kubectl get gatewayclass), and your certificate issuer’s annotation. The Gateway serves HTTPS with the certificate in the artbucket-tls Secret, and answers plain HTTP with a redirect. Its listeners use ports 443 and 80; a controller that binds listeners to its own entry points (Traefik: 8443 and 8000) needs those ports instead. Uploads go from browsers straight to storage, so the gateway needs no body size limit raised.

With cert-manager, turn on its Gateway API support (enableGatewayAPI: true in its config, 1.15 or later) and give an HTTP-01 issuer a gatewayHTTPRoute solver whose parentRefs name this Gateway. It then makes artbucket-tls from the annotation.

When your cluster already runs a shared Gateway, delete the Gateway from gateway.yaml and point both routes’ parentRefs at it, with its namespace and the sectionName of its HTTPS and HTTP listeners. The shared Gateway’s listeners must allow routes from the artbucket namespace.

Terminal window
kubectl apply -k .
kubectl -n artbucket rollout status deployment/artbucket

The pod migrates the database before it answers; its probes read /icon.svg, a static file, so they never query the database. /api/health does: 200 when the database answers within a second, else 503, for a load balancer that should stop sending traffic while it can’t, or a check after a deploy. Make the first account at your domain.

The base runs one replica. More work: migrations run under a lock and the sweeper is safe twice. The rate limit counts per pod, so each allows RATE_LIMIT requests a minute on its own.

It asks for half a CPU and 1 GiB, and may use up to 4 GiB: an upload of up to 512 MB is buffered while its previews are made.

Keep your changes out of the base with an overlay of your own:

resources:
- github.com/pwnera/artbucket//deploy/kubernetes/app?ref=main # or a release tag
images:
- name: ghcr.io/pwnera/artbucket
newTag: "1" # or a version the registry lists, such as "1.8.1"

Releases from before app/ keep the base at //deploy/kubernetes: pin a ref that has the folder you point at.

With a secrets manager (External Secrets, Sealed Secrets), make a Secret named artbucket-secret there and drop the secretGenerator from the base.

Change newTag in kustomization.yaml ("1" follows the major line) and apply again. The new pod migrates, then takes over. See Upgrading.