Getting started#

All guides · Next: Manage applications in the browser

Choose one path below. Demo mode lets you practice. Live mode connects to real servers. You do not need to set up both.

Where to run the commands: on the computer that will run the manager, in the Zela project folder. The browser address 127.0.0.1 always means the computer where that browser is running. If the manager is on another computer, ask your server administrator to set up secure remote access.

Try Demo mode#

1. Start the practice dashboard#

In a terminal in the project folder:

go run ./cmd/zela-server --demo

Leave this terminal open. The first run may take a while as Go downloads dependencies and builds Zela.

2. Find your sign-in token#

Open a second terminal in the same project folder:

cat ./data-demo/admin-token

Copy the displayed value. This token is your administrator password; keep it private.

3. Open Zela#

Open http://127.0.0.1:8080 and paste the token into the sign-in screen.

Check: you should see a Demo environment banner and sample workers. Try opening Workers, Deployments, Monitoring, and Activity log.

Demo deployments and Docker network changes are simulated. They do not create websites or change real servers. Configure network is disabled because the encrypted cluster network needs real Linux agents.

4. Stop or return later#

Press Ctrl+C in the first terminal to stop the demo. Run the same start command to return to it. Saved demo configuration lives in data-demo; live configuration uses a separate location.

To switch to real servers, stop the demo and choose a live path below. There is no Demo/Live switch inside the dashboard, and the sample workers are not converted into real servers.

Run a live manager with Docker Compose#

This starts the manager and database only. It does not install an application worker. You will add a real worker after signing in.

1. Confirm Docker is available#

Start Docker, then run:

docker --version
docker compose version

Check: both commands should print a version. If either command is missing, install Docker with its Compose plugin before continuing.

2. Set the database password#

For a new installation, copy the example configuration:

cp .env.example .env
chmod 600 .env
openssl rand -hex 32

Copy the random value from the last command. Open .env in a text editor and replace replace-with-a-random-password with that value. Save the file. Leave the other settings as they are for now.

Keep this file: it contains your database password. Do not recreate or change the password on an existing installation without coordinating the database change. Do not commit .env to source control.

3. Start Zela#

docker compose up --build -d
docker compose ps

The first command builds the image and starts the services in the background. The second lists them.

Check: postgres should become healthy, and zela-server should be running. If startup fails, inspect the output:

docker compose logs --tail=80 zela-server postgres

4. Sign in#

docker compose exec zela-server cat /data/admin-token

Open http://127.0.0.1:8080 on the manager computer and use the displayed token. With this default setup, the dashboard is accessible only on that computer.

Check: there should be no Demo environment banner. An empty worker list is expected.

5. Connect a worker and deploy#

Follow Connect your first worker, then Deploy your first application.

The manager container does not have access to your computer's Docker socket. For this path, use a reachable Linux worker through SSH provisioning or a separately installed worker agent. Do not enter unix:///var/run/docker.sock or 127.0.0.1 to reach the computer outside the manager container.

Stop, start, or restart later#

Run these from the same project folder:

Keep the same .env file and named data volumes. Do not use docker compose down -v to stop Zela: the -v option deletes its saved data volumes. Back up important installations using Operations.

Use native binaries#

This path runs Zela directly instead of inside Docker. Run in the project folder:

make build
./bin/zela-server --worker-binaries ./bin

Leave the server running. In a second terminal in the same folder:

cat ./data/admin-token

Open http://127.0.0.1:8080 and sign in. With no database configured, Zela stores its configuration in private files in data.

For a local single-host trial, a native manager can connect to the same computer's Docker socket if its user has access. See local Docker connection. Linux workers running the agent are needed for the encrypted cluster network and host measurements.

For a background Linux service, remote HTTPS access, or a separately managed database, follow Installation.

Your first deployment#

The full walkthrough is in the browser management guide. You will connect an online, active worker, deploy one copy of nginx:alpine, watch Activity log, and open the website using the worker's address.

If something does not work#

Next: connect a worker and manage an application.