Run Versola locally — Versola Docs
/docs
Pre-1.00.7.5versola.ioGitHub
RUEN

Run Versola locally

Start the full Versola stack on your machine with Docker and versola-cli, sign in to the admin console and tear it down again.

This page starts the full stack, central, auth, edge, Postgres and a proxy, on your machine and signs you in to the admin console. You need the CLI installed and a running Docker.

The local stack is a throwaway demo. Do not expose it to a network and do not use it for real users.

Prerequisites

  • Docker with the Compose plugin, running.
  • About 4 GiB of memory available to Docker (three JVMs and Postgres) and about 4 GiB of free disk space for the images. versola doctor checks both.
  • Port 2821 free on 127.0.0.1. The local proxy listens there.

1. Check the machine

versola doctor

Each check prints a result: Docker daemon, Compose plugin, port 2821, Docker memory and free disk. When all pass, it ends with:

All checks passed — ready for `versola bootstrap local <version>`.

If Docker is missing, doctor offers to open an install page in your browser. It never installs anything itself.

2. Bootstrap

Replace <version> with a Versola release number without the leading v, for example 0.7.0. The latest release is listed on the GitHub releases page.

versola bootstrap local <version>

bootstrap runs three steps in order: configure (generates configuration and secrets), migrate (creates the database schemas) and up (starts the containers). It pulls the images on the first run, which takes a few minutes. When it finishes, it prints:

Versola <version> is running at http://localhost:2821
Login: admin / Admin1234!

Then it opens the admin console in your browser. To skip that, add --no-browser:

versola bootstrap local <version> --no-browser

The console is always at http://localhost:2821/central/admin/.

3. Sign in

  1. Enter the username admin and the password Admin1234!.
  2. Enter the one-time code 123456.
  3. Set a new password when prompted.

These credentials exist only in the local demo. The stack runs in a non-production environment, which is why the sign-in code is fixed and no message is sent. A server deployment generates a random password instead.

Note: Repeated wrong codes or passwords lock the account temporarily. With the default limits, five wrong one-time codes or ten wrong passwords in an hour block the sign-in for 30 minutes, and the screen shows Access Denied even for the right code. Wait it out. The limits are described in User.

Check that the containers are healthy at any time:

versola status

Stop and remove

Stop the containers and keep the data and the images:

versola down

versola down --volumes also deletes the Postgres data volume. To remove everything the local stack created, run:

versola uninstall

uninstall stops the stack, deletes its Postgres volume, removes the pulled Docker images and clears the local state in ~/.versola/active. It asks for confirmation (-y skips it). It keeps ~/.versola/openbao, which holds credentials for other targets, and it does not remove the versola binary. It prints the binary path so you can delete it yourself.

Apple Silicon

The auth, central, edge and versola-tools images are published for linux/amd64 and linux/arm64, so Docker on Apple Silicon pulls native images and needs no emulation setting.

Next steps