Local development¶

With Docker (recommended)¶

You only need Docker with Compose.

git clone https://github.com/sylergydigital/Vistilla.git
cd Vistilla
docker compose up --build

Open http://localhost:8787. localhost counts as a secure context, so screen recording works without HTTPS.

What docker-compose.yml gives you:

the runtime image, storing objects on a volume (VISTILLA_STORAGE=fs);
./web mounted read-only into the container, so edits to pages, scripts and styles show up on reload without rebuilding;
port ${VISTILLA_PORT:-8787}.

On a small machine, build with fewer parallel jobs:

docker compose build --build-arg CARGO_BUILD_JOBS=1

With an S3 bucket (MinIO)¶

make up-minio

This adds MinIO as an S3-compatible store (API on port 9100, console on http://localhost:9101, user vistillaadmin) and points Vistilla at it.

Email locally¶

Without a mail setting, sign-up codes are written to the log:

docker compose logs -f api | grep "sign-up code"

Without Docker¶

You need a Rust toolchain. ffmpeg is optional, but needed for trimming, seek indexing, silences and AI audio.

cargo build -p vistilla-api
mkdir -p data
VISTILLA_BIND=127.0.0.1:8787 \
VISTILLA_DATABASE_URL="sqlite://./data/vistilla.db?mode=rwc" \
VISTILLA_FS_ROOT=./data/objects \
VISTILLA_WEB_ROOT=$PWD/web \
target/debug/vistilla-api

Make targets¶

Target	Runs
`make up`	`docker compose up --build -d`
`make up-minio`	The same, with MinIO
`make down` / `make reset`	Stop / stop and delete the volumes
`make logs`	Follow the server's log
`make ps`	Container status
`make build` / `make rebuild`	Build images (`rebuild` without cache)
`make test`	Run the Rust tests in Docker
`make fmt` / `make clippy`	Format / lint (warnings are errors)
`make smoke`	Run `scripts/smoke.sh` against the local stack
`make cli ARGS="…"`	Run `vistilla-cli` in the container

Working on the documentation¶

The docs are Markdown files in docs/, with the navigation in mkdocs.yml.

python3 -m venv .venv && .venv/bin/pip install mkdocs-material
.venv/bin/mkdocs serve       # live preview on http://127.0.0.1:8000

The Docker image builds them with mkdocs build --strict and serves them at /docs. Point VISTILLA_DOCS_ROOT at a built site/ folder to serve them from a local server.

Project layout¶

crates/vistilla-api/   the server (see Architecture > Backend)
crates/vistilla-cli/   the upload client
migrations/        SQL migrations, embedded into the binary
web/               pages, scripts, styles, icons, service worker
docs/, mkdocs.yml  this documentation
docker/            Dockerfile, Litestream config, hosted entrypoint
worker/            the Cloudflare Worker in front of the hosted instance
scripts/           smoke test, demo seed, mail relay, helpers
render.yaml        Render blueprint
docker-compose*.yml, Makefile