Guides

Domains and HTTPS

kvist serves your site and its API over plain HTTP on port 8080. To reach it on your own domain, something in front of it has to answer on HTTPS. This page has a ready-made setup for that, notes for using your own proxy, and how one server can host several sites.

The Obsidian plugin only connects over https:// (or to localhost), so your token is never sent unencrypted. Your site needs HTTPS before you can publish to it.

The ready-made setup: Caddy

Caddy is a small web server that gets and renews certificates from Let's Encrypt on its own. This setup runs it next to kvist, in the same Docker setup as Getting started.

  1. Point your domain at the server

    At your DNS provider, add an A record for your site's name (for example garden) with your server's IP address, and an AAAA record if the server has an IPv6 address. Open ports 80 and 443 in the server's firewall. Caddy needs both to get its certificate, so wait until dig +short garden.example.com prints your server's address.

  2. Add Caddy

    In the folder with kvist.toml (~/kvist), replace docker-compose.yml with the version that includes Caddy, and download Caddy's settings:

    cd ~/kvist
curl -fsSL https://raw.githubusercontent.com/klppl/kvist/main/deploy/docker-compose.caddy.yml -o docker-compose.yml
curl -fsSLO https://raw.githubusercontent.com/klppl/kvist/main/deploy/Caddyfile

    Your published notes and tokens are kept: they live in the same Docker volume as before.

  3. Put in your domain

    In Caddyfile, replace garden.example.com with your domain. Check that base_url in kvist.toml is the same address, starting with https://.

    garden.example.com {
	encode zstd gzip
	reverse_proxy kvist:8080
}

  4. Start it

    docker compose up -d

    Caddy gets a certificate within a minute. Check from your own computer:

    curl https://garden.example.com/api/v1/info

    If it doesn't answer, check that dig +short garden.example.com prints the server's IP, that ports 80 and 443 are open (Caddy needs 80 for the certificate), and read docker compose logs caddy. Behind Cloudflare's proxy, set SSL/TLS to Full (strict). From now on, docker compose pull updates Caddy along with kvist.

Your own proxy

If the server already runs nginx, Caddy, Traefik or a Cloudflare Tunnel, use that instead. Forward your whole domain, the site and /api/, to http://127.0.0.1:8080. The docker-compose.yml from Getting started already listens there, for the server itself only. Things to get right:

  • Keep the Host header. kvist picks the site by the domain a request was made for (see several sites). Most proxies pass it on by default; for nginx, add proxy_set_header Host $host;.
  • Allow large uploads. The plugin uploads files of up to 50 MiB by default (max_file_size). nginx stops at 1 MB unless you set client_max_body_size 64m;.
  • Use the same address in base_url, with https://. kvist uses it for links in feeds, the sitemap and social previews.

The deployment notes have a complete nginx example, including one that serves the built pages straight from disk. If Cloudflare's proxy is in front, see Cloudflare for the settings.

Several sites on one server

One kvist server can host several sites, say a personal garden and a work wiki, each on its own domain and with its own rules. Each site is a [[site]] block in kvist.toml:

[[site]]
id       = "garden"
base_url = "https://garden.example.com"
serve    = true
  [site.publish]
  always_public_folders = ["Kvist"]

[[site]]
id       = "work"
base_url = "https://notes.example.org"
serve    = true
  [site.publish]
  always_public_folders = ["Public"]

This is how the sites stay apart:

  • Visitors: kvist matches the domain a request was made for against each site's base_url, and serves that site.
  • Storage: each site has its own folder in kvist's data, sites/<id>/, with its notes, builds and published pages.
  • Publishing: a token belongs to one site. Create tokens per site with --site, and enter that id as the Site in the plugin. The sites can come from different vaults, or from different people.
  • Settings: rules, theme and theme settings are per site, and each vault has its own settings note.

To add a site: add its block to kvist.toml, point its domain at the server, and give it its own block in Caddyfile (or your proxy):

garden.example.com {
	encode zstd gzip
	reverse_proxy kvist:8080
}

notes.example.org {
	encode zstd gzip
	reverse_proxy kvist:8080
}

Then restart, and create a token for the new site:

docker compose restart
docker compose exec kvist kvist token create --site work --name laptop

To remove a site later, see Starting over or removing a site.