Simple Step by Step Guide to Set Up an Interkit Server

What is this about?

This is a guide to set up an interkit server aimed at non-technical people. If you want to go through the process manually, please have a look at Set up your own interkit server

Overview

There are three steps

  1. Get a Domain
  2. Set up the Server
  3. Connect Domain and Server

Get a domain

Already have a domain?

Dou you already have a Top Level Domain such as myinstitution.com that you want to use (directly or with a subdomain such as interkit.myinstitution.com)? ☞ Continue with Server Setup

Need a new domain

If you want to have a new Top Level Domain such as myinterkit.com, there are many providers to chose from. Here are some examples:

This tutorial does not cover the domain registration process, please read on at the provider of your choice.

☝ You only need the domain registration – no hosting is required at this step

Set up the Server

Chose a provider

We want to set up the interkit server on a virtual server instance. There are many provider. Here are some examples:

Detailed steps for Hetzner

We will cover Hetzner because this is what we have used so far.

Set up an account and add payment details first. Then continue the process in the web interface:

  1. Go to the “Cloud Console” https://console.hetzner.cloud/projects
  2. Create a “New Project” and give it a name such as “interkit” or the name of your project
  3. Enter the project, click “Add Server” and chose these options:
Step Action
Location Chose a location that is close to you
Image Chose Ubuntu
Type Chose Shared and x86. Select a package with 2 or more vCPUs, for example CPX11. You can always increase this later if your project needs it.
Networking IPv4 and IPv6 (Default)
SSH key If you know what it is, you can add a public SSH key, otherwise just keep it empty
Volumes keep blank
Firewalls keep blank
Backups Not required, but you can check Backups for additional recoverability in case of failure
Placement groups keep blank
Labels keep blank
Cloud config Copy & Paste this script 
#cloud-config
# ^^^ no space between # and cloud-config --> #cloud-config !
package_update: true
package_upgrade: true
timezone: "Europe/Berlin"
packages:
  - apt-transport-https
  - ca-certificates
  - curl
  - gnupg-agent
  - software-properties-common
runcmd:
  # install docker and docker compose (https://docs.docker.com/engine/install/ubuntu/)
  - install -m 0755 -d /etc/apt/keyrings
  - curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
  - chmod a+r /etc/apt/keyrings/docker.gpg
  - echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
  - apt-get update
  - apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
  - systemctl start docker
  - systemctl enable docker
  # download interkit docker compose definitions
  - cd /root
  - wget https://gitlab.interkit.app/interkit/interkit-experiments/-/raw/v04/docker-compose.env.live.example
  - wget https://gitlab.interkit.app/interkit/interkit-experiments/-/raw/v04/docker-compose.yml
  - wget https://gitlab.interkit.app/interkit/interkit-experiments/-/raw/v04/docker-compose-proxy-live.yml
  # download scripts
  - wget https://gitlab.interkit.app/interkit/interkit-experiments/-/raw/v04/env-configure.sh && chmod +x env-configure.sh
  - wget https://gitlab.interkit.app/interkit/interkit-experiments/-/raw/v04/env-randomize.sh && chmod +x env-randomize.sh
  # generate config
  - cp docker-compose.env.live.example .env
  # ... randomize passwords
  - ./env-randomize.sh
  # set domain and password here!
  # - replace "myinterkit.app" with your domain
  # - replace "mypassword" with your password
  - ./env-configure.sh -d myinterkit.app -p mypassword
  # docker compose setup
  - docker network create frontproxy
  - docker compose -f docker-compose.yml -f docker-compose-proxy-live.yml up -d
  # setup swapfile 2GB
  - fallocate -l 2G /swapfile
  - chmod 600 /swapfile
  - mkswap /swapfile
  - swapon /swapfile
  - echo "/swapfile swap swap defaults 0 0" >> /etc/fstab

☝ Important: Find the line - ./env-configure.sh -d myinterkit.app -p mypassword and replace “myinterkit.app” with your domain or subdomain (myinstitution.com or interkit.myinstitution.com)
☝ Important: Replace “mypassword” with a real password in the same line
Name Chose a name, for example: “interkit”
  1. Click Create & Buy Now
  2. The server is now spinning up and installing interkit.
  3. Copy the Public IP that was assigned to your new server that is spinning up.
  4. Continue with Connect Domain and Server immediately.

Connect Domain and Server

The Three Subdomains

The interkit server needs three subdomains to operate:

  • app.
  • api.
  • admin.

For example, if you chose interkit.myinstitution.com above, this will result in

  • app.interkit.myinstitution.com
  • api.interkit.myinstitution.com
  • admin.interkit.myinstitution.com

This is how you can reach your interkit server once it is set up and connected. You need to add just one A-Record to connect it all.

Add A-Record to Nameserver

Go back to your Domain Provider and find the settings for DNS also known as Nameserver.

Add a new entry of type A also known as A-Record with the value set to the public IP address copied in the end of the previous section.

Name Type Value
*.interkit.myinstitution.com A Public IP addres of your server

Finish

The server needs a few minutes to set up and connect. After that, you should be able to reach it at

https://admin.interkit.myinstitution.com

Username: admin
Passwort: the one you set up above

Troubleshooting

Cannot reach domain DNS_PROBE_FINISHED_NXDOMAIN

Your domains are known publicly. Check if there are typos in your domain setup. Sometimes it takes a while until everything is up to date. You can restart your computer and router to speed it up.