Introduction

Welcome to the new Liphium Documentation, specifically for Town administrators. This will from now on be the place where all advanced tutorials will be put. If you're here as a regular Liphium user wondering how to do some stuff in the app, you may wanna go to the help & resources page on the main website.

For now, we just have the guide on how to set up a Town using Docker.

If you're looking at this and wondering how to migrate from 0.4.0 to 0.5.0/0.5.1, you check out the migration guide.

Town setup

Welcome to the part of the documentation where I teach you how to deploy a town on your own server. Please understand that I don't have infinite time to cover every method, so if you have anything missing, you can contribute it on the GitHub repository for this page. I'm happy about every single thing we can add to this documentation because there are always people that use something different than you.

If you have any question and don't know where to look, you might want to take a look at the frequently asked questions about setup.

For now we have the following guides available:

• Creating a Town using Docker

If you want to change anything about your config or need an explanation for anything in the environment file, you can go straight to the configuration guide.

Docker

So you want to make your own town, eh? Well if you've never touched a server you probably shouldn't attempt this as servers (especially with Linux) are not a newbie-friendly environment. But with that out of the way or if you're seeking a challenge, let's get a fresh new town onto your server!

Also before we get started, you can always message me on Discord if you have any kind of problem with the installation or have some kind of other question. You can get to the Liphium Discord server through the invite in the navigation bar or menu at the top of the page.

One more thing I want to add is that the software we're going to be installing is called station. It's the backend I created that acts as the base of your town. Just so you aren't confused when you read it throughout this guide.

Requirements

Please make sure you have everything you need before trying to install station because otherwise it can be quite a bit of pain to get everything set up.

• A domain that you will never change or sell (because otherwise the entire platform falls apart as the client relies on this)
• A mail server for Liphium to send you emails with SMTP credentials (it is required or registration will fail when people try to make an account).
• A PostgreSQL server that you can connect to.

Tools we will use

Alright, one more thing before we get started on the installation. I just want you to know what we are going to use so everything is clear. I'll have instructions on how to install Nginx and Certbot later. Although I just link you to their websites, respectively.

• Nginx: Nginx is a reverse proxy for web requests that we'll use to expose your Liphium town to the outside world. We use it here because we're gonna create multiple domains pointing to one server and that wouldn't be possible without Nginx. We also need it to install SSL certificates for your domain so you can use the app properly.
• PostgreSQL: The database we're going to use for Liphium. All of your data is stored in here.
• Certbot: Well, this is gonna be the way we make your Liphium town secure by installing SSL certificates for your domain. It's completely free and really easy to use. I even donated 10€ because it's just awesome. Getting certificates was really difficult in the past, and you can donate, too.
• Docker: Docker is going to be used to install the actual Liphium server (called station) onto your server. We're going to install PostgreSQL using Docker as well.

With all of that explained, let's finally get to installing.

Step 1: Getting your PostgreSQL server ready

Connect to your PostgreSQL server and let's create a few databases. We're going to need two databases: One for all of the accounts and one for all of the chat messages. You can create those two by typing CREATE DATABASE chat; CREATE DATABASE main;. Different names can also be used, just be sure to use the correct ones later.

Step 2: Creating the actual Liphium town

1. Alright, now it's time for you to venture out by yourself for the first time. And that's to installing Docker. They have amazing documentation over there and you should hopefully be able to get it running your machine. Complete it until the end where they tell you to run the hello-world image and when you've done all of that, you can come back here.

2. If you haven't done so already, it's a good time to make a folder for all of the files for your Liphium town now (like /home/liphium or something). But now, let's pull the official Liphium image from Docker Hub: docker pull liphium/chat:latest.

3. Before we start getting into the configuration file, it's a good time to actually get your domain records set up. They will sometimes take a long time to be applied and if we're lucky they will already be ready when we get to actually connecting to the town.

4. Now let's create the configuration/environment file for your Liphium town. To do this, please follow our config setup guide and come back here once you finished creating the config.

5. If you chose local storage for your files, please create a folder called files in the current directory. All of your files will go into there.

6. Now run the docker container by using the command below. Make sure to replace config.env with the name of your environment/configuration file (or leave it alone if you called yours config.env).

docker run --env-file config.env -p 127.0.0.1:4002:4002 -p 127.0.0.1:4001:4001 -p 127.0.0.1:4000:4000 -v ./files:/home liphium/chat

7. Alright, after running the container once, it should print out that you should set TC_PUBLIC_KEY and TC_PRIVATE_KEY. Take the thing the container printed out and just add it to the bottom of config.env. Make sure to set both of those environment/configuration variables from the same run of Liphium. Otherwise they are not going to work together. Also make sure you remove the all the spaces and the double quotes. It should look something like this: TC_PUBLIC_KEY=value. value should not be surrounded by ", otherwise starting your town will not work. Do the same for TC_PRIVATE_KEY as well.

8. Now, for the last time, run the container again. It's going to ask you to set the SYSTEM_UUID environment variable to the thing it prints out. Also give it the same treatment as above and make it look like this: SYSTEM_UUID=value. value should again not be surrounded by ", otherwise station will not work.

9. Your setup of the main Liphium town is now complete. You should now be able to just run the thing and it should already be connecting to the database. The only thing that shouldn't work is grabbing the server public key. But we're going to fix that now.

Step 3: Exposing your town to the internet with Nginx

1. First, you of course need to install Nginx. If you are on Ubuntu or Debian, you can just run the command below. If not, you might have to look up a tutorial on how to do it or just use the package your package manager provides (if it exists).

apt install nginx

2. After installing Nginx, we're going to need to set up a few sites. There should already be a directory called /etc/nginx/sites-available, but if it is not there, just create it. Enter this directory.

3. Now you're going to need a few configurations again. Create the files in the /etc/nginx/sites-available folder as specified below:

File name: liphium-main

server {
  server_name main.example.com;

  location /v1/account/files/upload {
    client_max_body_size 10m; # Change this based on your preferences (10m = 10 megabytes)
    proxy_pass http://localhost:4000;
  }

  location / {
     proxy_pass http://localhost:4000;
  }
}

File name: liphium-chat

server {
    server_name chat.example.com;

    # Live share subscribe
    location /liveshare/subscribe {
        proxy_http_version 1.1;

        proxy_connect_timeout 7d;
        proxy_send_timeout 7d;
        proxy_read_timeout 7d;
        proxy_buffering off;
        proxy_cache off;

        proxy_set_header Connection "keep-alive";
        chunked_transfer_encoding off;

        proxy_pass http://localhost:4001/liveshare/subscribe;
    }

    # Zap upload endpoint (just to make sure nothing happens)
    location /auth/liveshare/upload {
        proxy_http_version 1.1;
        client_max_body_size 1100k;
        proxy_pass http://localhost:4001/auth/liveshare/upload;
    }

    # WebSocket endpoint
    location /gateway {
        proxy_http_version 1.1;

        proxy_connect_timeout 7d;
        proxy_send_timeout 7d;
        proxy_read_timeout 7d;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_pass http://localhost:4001/gateway;
    }

    # Every other endpoint
    location / {
        proxy_pass http://localhost:4001;
    }
}

File name: liphium-spaces

server {
    server_name spaces.example.com;

    # The WebSocket gateway
    location /gateway {
        proxy_http_version 1.1;

        proxy_connect_timeout 7d;
        proxy_send_timeout 7d;
        proxy_read_timeout 7d;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_pass http://localhost:4002/gateway;
    }

    location / {
        proxy_pass http://localhost:4002;
    }
}

4. Change the domains in the configurations (behind server_name) you just downloaded from me to reflect your domain setup (for example: main.example.com -> main.liphium.com). Make sure to not forget the semicolon at the end!

5. Let's make Nginx actually use those configurations. To do that just run the commands below to create links to the files in the /etc/nginx/sites-enabled folder.

ln -s /etc/nginx/sites-available/liphium-main /etc/nginx/sites-enabled/liphium-main
ln -s /etc/nginx/sites-available/liphium-chat /etc/nginx/sites-enabled/liphium-chat
ln -s /etc/nginx/sites-available/liphium-spaces /etc/nginx/sites-enabled/liphium-spaces

6. Run nginx -t to validate that the configurations work properly. If they don't, do what the command tells you to fix the configurations up bit by bit.

7. You can now restart Nginx by typing systemctl restart nginx. You should now have the configurations loaded.

8. Try to go to one of your domains, like http://main.example.com (replaced with your domain) and see if there is a nginx error there. If there is, everything worked. If there isn't, everything could still be working fine and your domains could just not be updated yet. As I specified above, that can take up to 48 hours.

Step 4: Adding SSL certificates to your town using Certbot

1. For Certbot to work, there are actually two things you need to install. You can follow this guide from the official website. Please follow their guide until step 5.

2. To secure your town, we first need to make sure your domains are already updated and already redirect to the correct server. To verify if they are already set up correctly, go to main.example.com (replaced with your domain) and check if there is some sort of error from nginx. If it's not there yet, you'll have to wait a little bit before getting your certificates. This is because your domain isn't pointing to the server yet. This can take up to 48 hours to happen in some cases. So if this happened to you just be patient for now, I know this sucks, but it can happen.

3. When you did see the error from nginx, you can now just run certbot --nginx to apply the certificates. The CLI will ask your for a few things. For example, they'll ask you to enter your email address. Please do, so you are always notified if something is wrong with your certificates. When they finally ask which domains you want to secure, just leave the field blank to select all of them. Certbot will then do its magic and you are officially done with the setup.

Step 5: Getting into your town

You can now use any of the official client apps to connect to your Liphium town by using the main domain (the one you replaced main.example.com with until now). Make sure to not enter https:// or http:// in front of the domain.

You will then have to create an account using a email address, a password and a username. After entering your email, you will be asked for an invite. This is a token required for anyone wanting to create an account in your town. Each invite can only be used once and the value you set SYSTEM_UUID to in your configuration file is an invite station creates automatically. Use that one to create your account, you will automatically get admin permissions as well as long as you are the first account created.

If you want to take a look at the settings of your town, you can find all of that under the "Your town" category when you go to the settings in the Liphium app. If you want to invite other people to your town, you can go to Settings -> Invites -> Generate invite to create invites for other people to be able to create accounts in your town. I hope you have a lot of fun with Liphium, and wish you a nice rest of your day!

Configuration

This page will teach you all about the configuration file/environment variables required for your Liphium town. If you haven't followed a guide for installation, please find one that suites your needs right in the menu/sidebar.

If you came here from an installation tutorial, you can skip straight to the creating a new configuration part.

An overview of the configuration

First, here is a basic overview with explanations of every configuration value.

# Domain config
#
# The base paths of all your servers and their servers. Liphium uses this
# to tell the client the domain of the server.
BASE_PATH=main.liphium.com
BASE_PORT=4000
CHAT_NODE=chat.liphium.com
CHAT_NODE_PORT=4001
SPACE_NODE=spaces.liphium.com
SPACE_NODE_PORT=4002

# App config
#
# APP_NAME is used in emails (you can change it) to the people in your town.
# The other values should just be kept the default (if you're not a dev).
# LISTEN is what address station will listen on.
# CLI enables a command line utility for developers (off by default).
# PROTOCOL is how the backend will contact the chat server and space station.
APP_NAME=Liphium
LISTEN=0.0.0.0
CLI=false
PROTOCOL=https://

# Test mode config
#
# TESTING is if station should be ran in testing mode or not.
# We recommend leaving TESTING on to see logs more clearly and be able to report
# errors to us more easily.
# TESTING_AMOUNT generates testing tokens. 0 is the best value to keep it at.
# If it isn't there, station will crash on startup.
TESTING=true
TESTING_AMOUNT=0

# SSO
#
# If you want to enable SSO, you can fill in the values below.
# Just keep in mind that this will be the ONLY LOGIN METHOD. I want to make this
# better in the future and support multiple SSO providers, but for now this is how
# SSO works. If you are working at a company, this is probably the best way of handling
# auth for your employees.
# SSO_ENABLED=true
# SSO_CONFIG = "https://auth.example.com/.well-known/openid-configuration"
# SSO_CLIENT_ID = "id"
# SSO_CLIENT_SECRET = "secret"

# Database for the main backend server
#
# The database credentials the main backend will use for accounts, files and more.
DB_USER=postgres
DB_PASSWORD=pw
DB_DATABASE=main
DB_HOST=address
DB_PORT=5432

# Database for the chat server
#
# The database credentials the chat server will use for conversations, status
# and more.
CN_DB_USER=postgres
CN_DB_PASSWORD=pw
CN_DB_DATABASE=chat
CN_DB_HOST=address
CN_DB_PORT=5432

# The secret for all JWT tokens used by Liphium, mostly connection tokens.
JWT_SECRET=generate_some_random_value

# File storage configuration
#
# How and where your files are stored.
# This should not be modified unless you know what you are doing. Read:
# https://docs.liphium.com/setup/config-setup.html#file-storage-configuration
FILE_REPO_TYPE=local
FILE_REPO=/home

# SMTP credentials
#
# The SMTP credentials used to connect directly to your mail server.
SMTP_SERVER=mail.example.com
SMTP_PORT=0000
SMTP_IDENTITY=liphium
SMTP_FROM=no-reply@example.com
SMTP_USER=user
SMTP_PW=pw

# A public and private key for reverse proxy protection.
#
# I commented it out here because I wanna prevent weird errors because of station
# generating this automatically and then the user having to paste it into this file.
#
# TC_PUBLIC_KEY=key_here
# TC_PRIVATE_KEY=key_here

# The UUID for the system (will also be printed by station)
# SYSTEM_UUID=uuid_here

File storage configuration

First of all, do not change your file storage configuration if there are any files uploaded to your instance. There are ways to change it, but I currently don't want to write documentation about it. If you run into this case, please create an issue in this repository and I will provide instructions on how to migrate. The process is too complicated to explain here.

If you don't want to change it, but just learn how to configure it, here is an overview:

FILE_REPO_TYPE=local
FILE_REPO=/home

FILE_REPO_TYPE=r2
FILE_REPO_KEY_ID=s3_key_id
FILE_REPO_KEY=s3_secret_key
FILE_REPO=s3_bucket_url
FILE_REPO_BUCKET=s3_bucket_name

Creating a new configuration

This guide is specifically for creating an environment/configuration file for your town. If you aren't coming from one of the official tutorials or some installation guide, please follow that first, until you are sent back to this page.

1. You already created subdomains on your domain for each of the servers that Liphium exposes in step 3. Change the following values of the configuration file above to point to your domain (replace example.com with your domain):

• BASE_PATH=main.example.com
• CHAT_NODE=chat.example.com
• SPACE_NODE=spaces.example.com

Please do not add https:// or http:// to your domain. This is a common issue that breaks functionality of Liphium.

2. You created a main and chat PostgreSQL database before in this guide. Please also fill the data needed for the connection into the following configuration fields:

• DB_USER=your_username
• DB_PASSWORD=your_password
• DB_DATABASE=main
• DB_HOST=postgres_address (to reach the local system use 172.17.0.1 instead of localhost, here's why)
• DB_PORT=5432 (default port of postgres)

Now repeat the same for the database configuration of the chat server:

• CN_DB_USER=your_username
• CN_DB_PASSWORD=your_password
• CN_DB_DATABASE=chat
• CN_DB_HOST=postgres_address (to reach the local system use 172.17.0.1 instead of localhost, here's why)
• CN_DB_PORT=5432 (default port of postgres)

3. Please generate a random string on some website or in your favorite password manager to paste into the JWT_SECRET configuration value. Please be sure to make it extra long (like 80-100 characters should be enough) as this is a really important thing that you don't want others to guess. You can also not change this very easily in the future. So make sure you use something random and very long.

4. Now change the following configuration values for your mail server that Station will use:

• SMTP_SERVER=mail.example.com (the domain of your mail server, replace example.com with your domain)
• SMTP_PORT=your_smtp_port (Liphium sends mail over TLS, so please use the TLS port for your mail server, in most cases: 587)
• SMTP_IDENTITY=your_smtp_identity (you can just leave this empty if your mail server doesn't tell you a specific value)
• SMTP_FROM=no-reply@example.com (the email you want Liphium to use)
• SMTP_USER=your_smtp_username
• SMTP_PW=your_smtp_password

5. Now you need to decide which kind of storage you want to use for your files. If you just want a folder, go to the local storage tab below. If you want to use Cloudflare R2, AWS S3 or other file storage providers, click the tab for that.

FILE_REPO_TYPE=local
FILE_REPO=/home

FILE_REPO_TYPE=r2
FILE_REPO_KEY_ID=s3_key_id
FILE_REPO_KEY=s3_secret_key
FILE_REPO=s3_bucket_url
FILE_REPO_BUCKET=s3_bucket_name

You've now successfully created a configuration for your town. More values will need to be added, but each tutorial will cover that in the next few steps.

Frequently asked questions about setup

Why do I need a domain for my town?

Alright, there are two reasons for this, let me explain.

First, if you don't have a domain, the server address of your town will be in all of the addresses of all of the people in your town. This would mean that if the address of the server ever changes (like if you want to move to a more powerful machine) everyone would lose their connections to people outside of your town. It would break everything in decentralization. The Liphium server is also designed in a way where it never expects to have the address of it change. Meaning if you don't have a domain and want to change the address of your server, you'll go through a lot of complaints from the people in your town losing connections to friends in other towns. And you'd have to delete all of the accounts as the server can't change the address of the friends you've saved in your vault. Would be kinda bad wouldn't it?

Second, by default Liphium blocks all towns that are using an insecure protocol. And because you can't have HTTPS when you just use a plain IP address you will never be able to connect to any towns running on the default configuration (which is basically all of them) because there are major security implications if you were to actually use a town without HTTPS in production.

I hope you understood the reasoning for this requirement and make the right choice. I will not help you with any of this stuff and if any request of this issue ever reaches me, I will ignore it. But if you have a good, secure and reasonable idea of how to solve this problem for everyone without huge migrations and want to implement all of it yourself, feel free to file an issue as Liphium is open source. We can then discuss this further together.

Migration guides

Welcome to the official place for everything that breaks and changes in Liphium. If anything needs to be changed about your server configuration before updating your Town, you will find it here. Just click on the next version above the version you are currently using right in the sidebar and go through all of the guides until you reach the latest version.

We recommend to not enable auto updates on your Docker container simply due to breaking changes that might happen. This is not just during the Beta, but it will occasionally happen due to changes we have to make.

Migration to station 0.5.0

Just before we start, I just wanted to mention that your town will likely still run even with the current configuration. It's just that if you want to take full advantage of the update and most importantly, Spaces, then I would recommend sticking with me just a little bit longer. It's really not a lot of changes.

Everything that changed

• A lot of environment variables are now redundant and no longer needed because LiveKit support was removed with the 0.5.0 update.
• A new Nginx configuration has been added to the Docker guide to handle the new port that opened for Spaces.

How to migrate to 0.5.0

Let's remove some clutter from your config.env file first. Just as a reference, this is the file where all of your environment variables are stored. If it's not called config.env it doesn't matter.

1. You can safely remove any environment variable with the prefix SS_LK_ as they are not needed anymore due to the removal of LiveKit support.

2. MAX_FILE_SIZE, MAX_TOTAL_STORAGE and MAX_FAVORITE_STORAGE can also be removed. These things can now be configured by going to Settings > Town > Files.

Now for the Nginx configuration. I actually didn't change a whole lot there, so this is basically just copying a file into a directory. This part of the migration guide is only important if you followed the official Docker installation tutorial.

3. Go to /etc/nginx/sites-available where all of your configurations are stored.

4. Put the configuration below into a new file called liphium-spaces and add it to the folder and replace spaces.example.com with your domain.

server {
    server_name spaces.example.com;

    # The WebSocket gateway
    location /gateway {
        proxy_http_version 1.1;

        proxy_connect_timeout 7d;
        proxy_send_timeout 7d;
        proxy_read_timeout 7d;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_pass http://localhost:4002/gateway;
    }

    location / {
        proxy_pass http://localhost:4002;
    }
}

5. Link the file to the /etc/nginx/sites-enabled folder by running the command below (assuming you still named the file liphium-spaces).

ln -s /etc/nginx/sites-available/liphium-spaces /etc/nginx/sites-enabled/liphium-spaces

And a little apology

I'm sorry for rolling out this update in such a weird way. I learned from my mistakes and next time I'll make sure to provide migration guides and resources on what's new directly before the update and not when it's already out for a day.

Well, some of the problems with the recent update have already been fixed in a little update called 0.5.1 for the server and v0.5.2 for the client, respectively. I hope that this doesn't happen again and in the future all the releases will be thorougly tested before release. I complain about this myself all the time, so I also wanna prevent it for my own app.

And with that, I wish you a happy rest of your day and a lot of fun with Liphium!

Migration to station 0.6.0

Hi, it's time for another migration because of another Liphium update, how great! Well this time it's really not a lot, but if you used to official Docker guide to upgrade to this release, you'll have to migrate your Nginx config because it's no longer letting Zap through.

Everything that changed

• Zap got a few performance improvements and an improved chunking size of 1 MB. In our tests this always performed better than the 512 KB we had before. You can read more about that in the changelog.

How to migrate to 0.6.0

You just have to change your Nginx config for chat server (the thing handling chat messages) and add the following in front of location / {.

# Zap upload endpoint (just to make sure nothing happens)
location /auth/liveshare/upload {
  proxy_http_version 1.1;
  client_max_body_size 1100k;
  proxy_pass http://localhost:4001/auth/liveshare/upload;
}

That's it

Well that's already it for this release. We'll have more changes like this that require a little bit of reconfiguration throughout the year I assume, we wanna add audio and video calls back after all. As usual, thanks for using and supporting Liphium! And with that, I wish you a happy rest of your day.