Skip to Content
Skilder

Quick start

Run a self-hosted Skilder with Docker Compose, from the release files to the first administrator.

Pilot release. Self-hosting Skilder is a pilot.

A self-hosted Skilder runs from one Compose file, one .env file and one data directory. Docker publishes a single port, served over plain HTTP by the bundled proxy service.

Before you start

  • A host with Docker, the Compose plugin, git and openssl.
  • A DNS name for Skilder, for example skilder.example.com.
  • A reverse proxy that terminates TLS for that name and forwards every path to the published port. Reverse proxy and HTTPS lists what it must do.
  • Access from the host to GitHub and the image registries (Outbound access). Behind a forward proxy, or with internal services whose certificates your own certificate authority issued, also follow Private CA and outbound proxy.
  • The credentials Skilder sends you (Credentials).

Credentials

The release files and the Skilder images are private during the pilot. Skilder sends you:

  • a GitHub username and a token. The token clones the release files and pulls the images.
  • optionally, a deploy key: a private SSH key that clones the release files only.

Both are yours alone: Skilder can revoke them without touching anyone else's access.

The enterprise backend image, which adds single sign-on, is pulled with the registry access Skilder gives you for it. To use it, ask Skilder before you start.

Get the compose files

The compose file, the proxy configuration and .env.example are in the skilder-ai/self-hosted repository. Each release is a tag, v<version>, and main holds the newest one. Clone the release you run, with either credential:

git clone --config credential.helper=store \
  --branch v<version> https://github.com/skilder-ai/self-hosted.git skilder

Git asks for a username and a password: enter the GitHub username and the token. It saves them in plain text in ~/.git-credentials, so a later git fetch in this clone does not ask again. Once the old token stops working, the next fetch fails and forgets it: run the fetch again and enter the new token.

Run every docker compose command from the skilder directory. The repository ignores .env and data/, so neither ends up in a commit. Fetching a later release in this directory (git fetch --tags) uses the same credential. .env keeps the release you first cloned in IMAGE_TAG. Upgrade moves both to a later release.

Log in to the registry

Log in to ghcr.io with the GitHub username, and paste the token when Docker asks for the password:

docker login ghcr.io -u <username>

Run it as the user that runs docker compose: Docker keeps the login per user. When you get a new token, run it again. With SKILDER_REGISTRY set to a mirror, log in to the mirror instead (Data, ports and images).

Generate the secrets

docker compose refuses to start without six secrets. Generate them:

cd skilder
./init-env.sh

It copies .env.example to .env, readable by you alone, and generates every secret that is blank or missing. It never rewrites a secret that is set, so running it again is safe. Back up .env with the data directory: restored without its keys, an install cannot read its passwords, sessions and stored secrets. Secrets says what each one does.

Set the public URL

PUBLIC_URL is the https origin your reverse proxy serves: scheme, host and any port, no path. Set it on the PUBLIC_URL= line of .env:

.env
PUBLIC_URL=https://skilder.example.com

The bundled proxy publishes port 80 on every interface. With your reverse proxy on the same host, set SKILDER_HTTP_PORT to keep the port on this machine and off 80:

echo "SKILDER_HTTP_PORT=127.0.0.1:8080" >> .env

For a reverse proxy on another machine, see Before you start.

Configure the mail server (optional)

Without a mail server, the backend writes every sign-in code and link to its log instead of sending it. Set one now in .env, and Skilder sends email from its first start:

.env
EMAIL_PROVIDER=smtp
SMTP_HOST=smtp.example.com
SMTP_USER=skilder
SMTP_PASSWORD='...'
EMAIL_FROM=skilder@example.com
EMAIL_REPLY_TO=support@example.com

EMAIL_REPLY_TO defaults to Skilder's own inbox, so set it to yours. The connection uses STARTTLS on port 587. Send through your mail server lists the TLS, port and sender options, and Check email works shows how to confirm a send.

Start Skilder

docker compose up -d

On its first start, the backend creates the database and a workspace named Default. It applies the database schema on every start. A new database starts with every migration recorded as done, so there is nothing to migrate. On a later start, the backend refuses to start while a migration its release needs has not run, and its log names the command to run. Upgrade shows how to run it.

Create the first administrator

Open your PUBLIC_URL. Until the setup is done, every page opens the setup page. Enter an email address, choose a password of at least 8 characters with a letter and a number, confirm it, and accept the terms.

That account is the administrator of Default and the platform administrator of the install: it sees every workspace and account, and the runtime of each workspace. The first person to submit the setup page gets that access, so complete it right after the first start. To add another platform administrator later, open <PUBLIC_URL>/admin/platform-admins, enter the email of an existing account and click Add.

With single sign-on set up before this first start, an email on your SSO domains goes on to Continue with SSO (First start with SSO).

Before you invite anyone

Anyone who reaches the sign-in page can create an account, and gets a workspace of their own. To bring members into Default, invite them. Until you configure a mail server, the backend writes every sign-in code and link to its log, and anyone who reads that log can sign in as any member.

On this page