Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/noelzappy/vaulx/llms.txt

Use this file to discover all available pages before exploring further.

This guide gets Vaulx running on your local machine so you can explore the interface, test uploads, and understand the configuration before deploying to production. You have two options: the fastest path uses Docker Compose (everything spins up in one command), while the manual path gives you a live-reloading Go development environment.

​
Prerequisites

Before starting, make sure you have the following installed:
  • Go 1.25 — download
  • PostgreSQL 16 — only required for the manual setup; Docker Compose manages its own Postgres container
  • templ CLI — installation guide; required to regenerate server-side components after .templ file changes
  • sqlc (optional) — sqlc.dev; only needed if you change SQL query files
You will also need an S3-compatible bucket (the README and examples reference Hetzner Object Storage) and its credentials. Vaulx uses presigned URLs for uploads, so the bucket must be reachable from the browser.

​
Choose Your Setup

Docker Compose starts both the PostgreSQL database and the Vaulx application container with a single command.
1

Copy the example environment file

cp .env.example .env
2

Edit .env with your credentials

Open .env and fill in every variable. Pay particular attention to SESSION_SECRET (must be at least 32 random characters), your Hetzner Object Storage keys, and the admin seed credentials.
# .env — minimum required changes
SESSION_SECRET=replace-with-32-plus-byte-random-string
SEED_ADMIN_EMAIL=admin@yourdomain.com
SEED_ADMIN_PASSWORD=ChangeMe123

HETZNER_ACCESS_KEY=your-access-key
HETZNER_SECRET_KEY=your-secret-key
HETZNER_S3_ENDPOINT=https://fsn1.your-objectstorage.com
HETZNER_BUCKET=vaulx

# Docker Compose injects these into the Postgres container
POSTGRES_USER=vaulx
POSTGRES_PASSWORD=vaulx
POSTGRES_DB=vaulx
3

Build and start the stack

docker compose up --build
Docker Compose builds the Vaulx image, waits for Postgres to pass its health check, then starts the app. On first boot, migrations run automatically and the admin account is seeded.
4

Open the app

Navigate to http://localhost:8080 and log in with the email and password you set in SEED_ADMIN_EMAIL / SEED_ADMIN_PASSWORD.

​
Required Environment Variables

VariableRequiredDefaultDescription
DATABASE_URLYes—Postgres connection string, e.g. postgres://user:pass@host:5432/db?sslmode=disable
SESSION_SECRETYes—Random string ≥ 32 chars used to sign session cookies
PORTNo8080HTTP port the server listens on
SEED_ADMIN_EMAILYes—Email for the admin account created on first boot
SEED_ADMIN_PASSWORDYes—Password for the seeded admin (min 8 chars, at least one digit)
HETZNER_ACCESS_KEYYes—Hetzner Object Storage access key
HETZNER_SECRET_KEYYes—Hetzner Object Storage secret key
HETZNER_S3_ENDPOINTYeshttps://fsn1.your-objectstorage.comS3-compatible storage endpoint URL
HETZNER_BUCKETYesvaulxBucket name where files are stored

​
First Login

Once the server is running, open http://localhost:8080 in your browser. You will be redirected to the login page at /auth/login. Enter the email and password you configured in SEED_ADMIN_EMAIL and SEED_ADMIN_PASSWORD. After logging in you land on /files — your root file browser. From there you can:
  • Create folders and upload files via the Upload page
  • Manage users and roles from the Admin → Users panel
  • Browse the audit history at Admin → Audit Log
  • Generate share links from any file or folder context menu

​
Development Workflow

After making changes to source files you may need to regenerate code before the server picks up your changes: After changing any .templ file: 
templ generate
This regenerates the corresponding *_templ.go Go files in web/templates/. Run it before go run or your build will be stale. After changing SQL query files (files under internal/db/queries/): 
sqlc generate
This regenerates internal/db/*.go with updated type-safe query functions. You can also run both steps together using the Makefile: 
make generate
The session cookie is set with Secure: true, which means the browser will only send it over HTTPS. In local development this is fine because you access Vaulx directly at http://localhost (localhost is exempt from the Secure restriction in most browsers). In production, however, you must terminate TLS in front of Vaulx — otherwise the login flow will silently fail. See Deployment for how to add a domain and HTTPS.

Build docs developers (and LLMs) love

Get started for freeTalk to us