Getting started

Ten minutes, most of it DNS.

Five steps. Four of them are things you do before touching the server — the install itself is one command and four questions.

root shell on the server

curl -sSL https://raw.githubusercontent.com/AymericChaverot/quasar/main/setup.sh | sudo bash

Read it first if you like — it is setup.sh, in the repository.

01

What you need

A Linux server with root access. Ubuntu or Debian is the tested path; 1 GB of RAM is enough — the dashboard itself stays under 50 MB.
A domain name whose DNS zone you control. Quasar gives every app a subdomain of it, and the dashboard takes admin.
Nothing else. Docker is installed by the script if it is not already there.

02

Point the domain at the box

At your registrar, create both of these records. Do it before installing: Let's Encrypt can only issue a certificate once the name already resolves to the server.

Type	Name	Value
A	your-domain.com	the server's IP
A	*.your-domain.com	the server's IP

Both records are needed. The wildcard covers admin. and every app subdomain, but not the apex itself — an app published on @ stays without a certificate until your-domain.com has its own A record.

Delete the registrar's default records. Many zones ship with an A record on the apex pointing at the registrar's own shared hosting, plus a CNAME www. Left alongside yours, the browser sometimes lands on your server while Let's Encrypt lands on the registrar's placeholder page: issuance fails while everything appears to work. An app's TLS panel reports both cases.

03

Open three ports

Only 22 for SSH, and 80 and 443 for Traefik. Nothing else needs to be reachable — the Docker socket is never exposed, and the dashboard is served over 443 like any other app.

root shell on the server

ufw allow 22/tcp && ufw allow 80/tcp && ufw allow 443/tcp && ufw enable

04

Run the installer

As root, on the server. It installs Docker if needed, asks four questions — root domain, Let's Encrypt email, admin username, admin password — clones into /opt/quasar, generates the configuration, and starts the stack: Traefik, the socket proxy and the dashboard.

root shell on the server

curl -sSL https://raw.githubusercontent.com/AymericChaverot/quasar/main/setup.sh | sudo bash

05

Sign in

Open https://admin.your-domain.com and use the account you just created. The first load can take a few seconds — that request is what triggers certificate issuance. Every load after it is immediate.

Two things worth doing straight away:

Turn on two-factor authentication in Settings. This dashboard can start and stop everything you host.
Set the notification webhook, so a failed deploy or an app in an error state reaches you somewhere you actually look.

The admin account is only created on first start, while the users table is empty; setup.sh then strips the password back out of .env.

Updating

One click, and your apps never notice.

Instances check GitHub releases every six hours. When one is available, the System page offers it: an ephemeral updater container swaps the dashboard out. Only the dashboard is unavailable, for a few seconds. Running applications are not touched.

Publishing a release, if you run your own fork, is a tag push — the release.yml workflow builds the image, pushes it to GHCR and creates the GitHub Release that instances look for.

publishing a release from a fork

git tag v0.2.0 && git push --tags

GHCR packages are private by default. If you fork, make the package public — otherwise the server cannot pull it and setup.sh falls back to building the image locally. That works, but it is a great deal slower.

On the box

Everything lives in one directory.

No files scattered across /etc, no systemd units to hunt down. Back up /opt/quasar and you have backed up the platform — which is exactly what the built-in backup does.

The two files marked chmod 600 hold the secrets: global environment and the ACME account with its certificates.

/opt/quasar

/opt/quasar/
├── setup.sh
├── docker-compose.yml       # traefik + socket-proxy + dashboard
├── .env                     # global secrets (chmod 600)
├── traefik/
│   ├── traefik.yml          # static config, written by setup.sh
│   └── acme.json            # certificates (chmod 600)
├── storage/
│   └── database.sqlite
├── backups/                 # quasar-<date>.tar.gz
└── apps/<app-id>/
    ├── source/              # git clone, for build mode
    │   └── docker-compose.quasar.yml   # generated: the repo's compose, adapted
    ├── docker-compose.yml   # injected-compose mode
    ├── .env                 # passed to stacks as --env-file
    └── data/                # persistent volumes

Local development

Or just run it on your laptop.

The binary loads .env from the working directory at start — real environment variables still win, and ENV_FILE points it elsewhere. The dashboard comes up on localhost:8080 with the credentials from that file, and the database and apps go to .dev/.

COOKIE_SECURE=false is what lets the session cookie work over plain HTTP locally. Never in production.

on your machine

cp .env.example .env
docker network create traefik-net
go run ./cmd/server

before you push

go build ./...
go test ./...

Stuck on something?

The README carries the same steps with more detail, and issues are the right place for anything it does not cover.

Repository Every feature