Detailed Setup Guide#

In this page, we're going to go over setting up Kalmia on a Linux (Debian 12) machine. Here's the steps before we jump in

1. Install dependencies
2. Download Kalmia from the github repository
3. Setting up the config file
4. Setting up a systemd service
5. Setting up NGINX to reverse proxy requests
6. Using Kalmia 🥳

Install Dependencies#

We need node.js, npm and wget installed in order to get Kalmia working. You can follow the guide here for installing node js. On debian using apt you can install wget and like this:

sudo apt update && sudo apt install wget nginx

Downloading Kalmia#

All you have to do is go to the releases page and download the latest binary for your platform, as of writing the binary we would use is this one. Now we're going to assume you have shell access on the machine you will be hosting Kalmia on. If so, just connect to the server via SSH.

Once you're connected over SSH you can just go ahead and navigate to ~/ which is basically your home directory, this can be anything, we're using ~/ for simplicity. You can run the following commands to create a new directory for Kalmia and also to download the binary.

mkdir kalmia && wget https://github.com/DifuseHQ/Kalmia/releases/download/0.0.1/kalmia_0.0.1_linux_amd64 -O kalmia

Once you have that down we can move on to step two!

Setting up the config file#

Now the binary itself needs a config file to start working the format of which will be given in config.example.json, we will go over the options.

• environment: For anything other than a dev environment it is imperative to use "production" here if you're not writing/contributing to kalmia.
• port: Just a simple port number, choose something > 1024 as then you'd not need root privileges to run Kalmia.
• database: You can use either sqlite or postgres. For sqlite you just have to specify "sqlite" and for postgres you need to give a connection string similar to this:

postgres://user:password@postgres:5432/kalmia?sslmode=disable

• logLevel: We're still a 0.0.1 product, so leaving debug would be helpful just in case you encounter a bug and need our help to solve it! But other options such as "info", "error", "warn" are valid here.
• sessionSecret: This is used in the generation of JWT tokens, make sure you use a long, random string here that is NOT the default one in the example config.
• users: You can specify the initial users here. admin or not is determined by the boolean admin flag.
• s3: ANY S3 compatible object store will work here, just fill out the details from your favorite one.
• github/microsoft/google oauth: You can create one on their respective web interfaces and just copy in the credentials here.

Just a note regarding the oAuth the callback URL must be: http://localhost:2727/kal-api/oauth/github/callback replace the domain and port (if any) with your own.

Setting up a systemd service#

Navigate to /etc/systemd/system:

cd /etc/systemd/system

Create a new file called kalmia.service and paste following contents there (we're using nano, you can also use vi)

nano kalmia.service

[Install]
WantedBy=multi-user.target

[Service]
Environment="PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/root/.nvm/versions/node/v20.16.0/bin"
ExecStart=/root/kalmia/kalmia -config /root/kalmia/config.json
WorkingDirectory=/root/kalmia
User=root
Restart=always
RestartSec=15
StandardOutput=journal
StandardError=journal
SyslogIdentifier=%n

Make sure you replace the node binary location in the environment block (/root/.nvm/versions/node/v20.16.0/bin) to the path of the binary in your system, you can find out where npm/node lives by using the command whereis:

whereis npm

The above step is crucial as Kalmia uses npm and npx to build documentation. The service WILL panic if it doesn't find node, npm binaries.

Setting up a reverse proxy#

Now this step is entirely optional but highly recommended. We're going to be running kalmia on port 2727, which means nginx would run on 443 and 80. This would be an example config for kalmia.difuse.io:

server {
    listen 80;
    listen [::]:80;
    server_name kalmia.difuse.io;
    return 301 https://$host$request_uri;
}

server {
    server_name kalmia.difuse.io;
    listen 443 ssl;
    listen [::]:443 ssl;
    ssl_certificate /etc/tlsfiles/difuse.io.fullchain.pem;
    ssl_certificate_key /etc/tlsfiles/difuse.io.privkey.pem;
    client_max_body_size 64M;

    location = / {
        return 301 /doc;
    }

    location / {
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
        proxy_pass http://127.0.0.1:2727;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

You can follow the official nginx guide here if you'd like to know more about the options listed above.

Using Kalmia 🥳#

You can use your favorite browser to navigate to /admin and you should see the interface right there!