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.
Try it
Section titled “Try it”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.
git clone https://github.com/pwnera/artbucket.gitcd artbucketkubectl apply -k deploy/kubernetes/quickstartkubectl -n artbucket rollout status deployment/artbucketThen, each in a terminal of its own:
kubectl -n artbucket port-forward svc/artbucket 3000:80kubectl -n artbucket port-forward svc/s3 9000:9000Open 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:
kubectl delete -k deploy/kubernetes/quickstartThat deletes the namespace, its volumes and everything in them. The rest of
this page sets up the real thing, with app/.
Install
Section titled “Install”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:
kubectl apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.3.0/standard-install.yamlgit clone https://github.com/pwnera/artbucket.gitcd artbucket/deploy/kubernetes/appcp secret.env.example secret.env # git ignores itSettings
Section titled “Settings”config.env holds the plain settings and becomes a ConfigMap:
APP_URL=https://assets.example.comINTERNAL_URL=http://localhost:3000HOSTNAME=0.0.0.0S3_ENDPOINT=https://s3.eu-central-1.amazonaws.comS3_REGION=eu-central-1S3_BUCKET=acme-assetsS3_FORCE_PATH_STYLE=falseTRUSTED_PROXIES=privateKeep 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:
DATABASE_URL=postgres://artbucket:...@postgres.example.com:5432/artbucketS3_ACCESS_KEY_ID=...S3_SECRET_ACCESS_KEY=...BETTER_AUTH_SECRET= # openssl rand -base64 32Keep 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.
Domain
Section titled “Domain”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.
kubectl apply -k .kubectl -n artbucket rollout status deployment/artbucketThe 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.
Replicas and resources
Section titled “Replicas and resources”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.
Your own overlay
Section titled “Your own overlay”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 tagimages: - 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.
Upgrading
Section titled “Upgrading”Change newTag in kustomization.yaml ("1" follows the major line) and
apply again. The new pod migrates, then takes over. See
Upgrading.