Installation¶
This guide is the recommended starting point for self-hosting Validibot.
Validibot's preferred operator interface is the just command runner. It wraps
the underlying Docker Compose commands so the day-to-day workflow stays short
and consistent.
The same base installation works for Community, Pro, and Enterprise. Commercial editions add packages on top of the same self-hosted deployment.
What you'll need¶
Before you start, install:
- Docker and Docker Compose
just- At least 4 GB RAM for local evaluation
If you plan to run heavier validators regularly, use more memory. The deployment guides cover sizing in more detail.
Quick local setup¶
This is the fastest way to get a working instance on http://localhost:8000.
1. Clone the repo and copy the env templates¶
git clone https://github.com/danielmcquillen/validibot.git
cd validibot
mkdir -p .envs/.local
cp .envs.example/.local/.django .envs/.local/.django
cp .envs.example/.local/.postgres .envs/.local/.postgres
2. Replace the !!!SET...!!! placeholders¶
Open .envs/.local/.django and replace every !!!SET...!!! placeholder
with a real value. These are the secrets your instance will use for
signing, encryption, and the first admin login — Validibot will refuse to
start until each one is filled in.
| Placeholder | What it's for | How to generate one |
|---|---|---|
DJANGO_SECRET_KEY |
Django's cryptographic signing key (sessions, CSRF, password reset tokens). | python -c "import secrets; print(secrets.token_urlsafe(50))" |
DJANGO_MFA_ENCRYPTION_KEY |
Encrypts MFA TOTP seeds and recovery codes at rest. Required even if no one has MFA enabled yet. | python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" |
SUPERUSER_PASSWORD |
The password for the bootstrap admin account created on first boot. |
Pick a strong password — you'll use it to sign in. |
These files contain real secrets
.envs/ is gitignored for a reason. Never commit .envs/.local/.django
or any other env file to a public repository. Generate fresh values for
every deployment — never reuse a secret key or encryption key across
dev, staging, and production.
The .envs/.local/.postgres template is fine to leave as-is for local use;
its credentials only ever sit between the Postgres and Django containers on
your machine.
3. Start the stack¶
On first boot, Validibot initializes the local database and creates the
admin user from the values in .envs/.local/.django.
Sign in with:
- Username:
admin - Password: the
SUPERUSER_PASSWORDyou set
After the app is running¶
Once you can sign in:
- Follow the Getting Started guide to create your first workflow.
- If you purchased a commercial edition, continue to Self-Hosted Editions to add Pro or Enterprise features.
- If you are preparing a real production deployment, use the deployment guides below.
Production deployments¶
For production, keep using the just commands, but switch to the production
deployment workflow and environment files.
Start here:
- Docker Compose deployment responsibility
- Environment configuration
- Reverse proxy setup
- DigitalOcean deployment example
Those guides cover TLS, backups, sizing, and operator responsibilities in more detail than this quick-start page.