Calckey Installation Tutorial

Mon, Dec 12, 2022

Calckey is a micro-blogging 'social media' platform forked from Misskey. Similar to Mastodon and Twitter in the general sense of being a micro-blogging social media platform but with many unique features. The official Calckey repository and instructions can be found here on Codeberg. You can read here about what Misskey is, and then read about what makes Calckey different here.

I think the instructions in the git repo are probably fine enough for more knowledgeable people, but as someone that wasn't incredibly familiar with docker to begin with, it took me several tries to get Calckey up and running bouncing back and forth between the Misskey and Calckey instructions. I'm also using Apache instead of Ngnix, so I'll provide a simple reverse proxy example here for Apache. I wanted to write something up that might help some others in a similar situation if they would like to try and get a Calckey instance up and running.

I've gotten feedback from the developer of Calkey, @thatonecalculator@stop.voring.me, that he highly recommends the use of Ngnix over Apache for streaming, websockets, and performance reasons. Most everything below still would apply to an installation using Ngnix, just use the Ngnix example configuration from the git repo instructions linked above.

The first thing you're going to need is a machine to install this on. I am utilizing a VPS (Virtual Private Server) hosted with Hetzner. There are a ton of VPS providers out there and any should work for this exercise. You could also do this on a local machine to test it out if you like. If you're just testing or installing to run a single-user or small instance, you shouldn't need a tremendous amount of CPU or RAM. Sizing things for a larger instance is outside the scope of this tutorial, not to mention outside my area of expertise.

Next, you're going to need a web server running. I'm not going to get into installing and doing the main configuration for a web server here. I will be providing a basic reverse proxy configuration for Apache. The Calckey git repo instructions provide an example for using Ngnix. I'm not certain yet if I am missing anything important in my Apache configuration as I've only just begun playing around with my Calckey installation. If I find anything that I need to add to my configuration to either correct any functionality or improve performance, I will update the example on this page. It seems everyone is moving more and more towards Ngnix these days, but I originally learned Apache a bit way back when and have just stuck with that. Install your web server of choice and do your basic configuration for whichever OS you're running.

You'll need Docker and Docker Compose installed. I'm not going to detail installing these here. You can either look for instructions specific to your distro, or just following the instructions on the Docker website. As I am fairly new myself to Docker, I will be providing some basic examples of how to interact with and utilize Docker as we go through this tutorial. Some for my own reference in the future, but also because I'm targeting users who are similar to my skill level here, so I'll include what I think is helpful in understanding the basics of Docker containers and images.

You'll also need git installed. Well, technically, you could manually download the repo I suppose - but I'm going to walk through using git to download the repo here.

And lastly, you'll probably want to have certbot installed and configured to apply an SSL certificate from LetsEncrypt.

So to recap, I am using the following:

  • A VPS running Ubuntu Server 22.04.1 LTS
  • Apache 2.4.52
  • Docker and Docker-Compose
  • Git
  • Certbot

I've done a lot of different things with this particular VPS since I've created it. If you run into a missing prerequisite that prevents you from moving along, please let me know so I can include it here.

For my VPS, I have a single DNS entry that forwards all requests to Heavy.Rocks (including any subdomains) to my VPS. I then utilize Apache VirtualHost files for each subdomain that I want to host. I have chosen to use the domain smol.heavy.rocks for my Calckey instance. My Apache VirtualHost file is configured as follows:

As noted earlier, it is recommended by the developer to use Nginx instead of Apache. After getting Calckey running on the below Apache config, I found there were at least several things that were not working properly. Basically background updating to provide notifications, auto updating the feed with latest posts, providing status updates, were all not working. So while the below configuration will allow Calckey to 'run', this is far from a complete and fully functioning configuration. Rather than try to work out all what I needed to do to make it work more fully with Apache, I just chose to switch my server over to Nginx instead. If anyone comes up with a more complete Apache config, I would gladly add those details here for others.

<VirtualHost *:80>
  ServerName smol.heavy.rocks
  ProxyPreserveHost On
  ProxyPass / http://127.0.0.1:4000/
  ProxyPassReverse / http://127.0.0.1:4000/
  RewriteEngine On
  RewriteCond %{SERVER_NAME} =smol.heavy.rocks
  RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
</VirtualHost>

Once you've created the VirtualHost file in /etc/apache2/site-available you can enable the site using a2ensite, and then use certbot to apply the SSL Certificate.

Navigate to where you want to store the cloned git repo. This may not be best practice, but since I'm running it as a docker container, I'm just cloning the git repo into my user home directory. I could be wrong, but I don't think there is a major concern with this, at least not for me on a single user instance.

git clone https://codeberg.org/thatonecalculator/calckey.git
cd calckey/
# git checkout main # if you want only stable versions

We need to first make a copy of the example configurations and edit a few things. From within the Calckey git directory, perform the following:

cp .config/example.yml .config/default.yml
cp .config/docker_example.env .config/docker.env

Next, open up default.yml in your text editor of choice and set the following items:

  • Set the URL that will be used for your instance.
  • Set the port to the open port you want to use. I already had gitea running on port 3000, so I used 4000 for Calckey.
  • Since we are using Docker, under the db section, change the following items:
    • host: from localhost to db.
    • user: from example-calckey-user to calckey.
    • pass: from example-calckey-pass to YourSecurePasswordOfChoice.
  • Under the redis section, change host: from localhost to redis.

The above instructions might not be terribly clear. I'm adding the following screenshot to help make it more apparent what needs to be modified. The left side shows the example.yml file and the right is the modified default.yml.

Screenshot of Calckey configuration

That should be it to get a simple and basic installation running. There are obviously a lot of other options and parameters here that can be changed if required, but those are currently outside the scope of this tutorial.

Now open docker.env in your text editor and set the variables here to match what you put in the default.yml file for the database settings.

Lastly, if you are using a port other than the default 3000, open up the docker-compose.yml file in the main Calckey directory and be sure to change the port here to the one you are using.

At this point, if you have just installed docker for the first time and aren't all that familiar with it, I'll suggest looking at a couple of things here just to get a better understanding of how some of this works. If you run docker images on a fresh install of docker, you should not have any images shown yet. You'll just get a table of headers without any content shown under the table headers. Once we run the next few commands, if you run docker images again, you'll then see which docker images have been downloaded from the docker repository.

Now, run the following while in the Calckey directory:

docker-compose build
docker-compose run --rm web yarn run init
docker-compose up -d

The first two can take a little bit of time to process. It may even appear to hang at points. Be patient and wait until you arrive back at your prompt.

And that should be it. Once those have all completed, you should now be able to access your Calckey website. The first user to register is the administrator, so I recommend getting yourself registered quickly, especially if this is a public facing site. And now you can continue on with your configuration from within Calckey.

Here is a screenshot showing what you should see if you run docker images and docker container ls:

Screenshot of Docker Image Container Example

  1. Previous Post
    Ode to My Son, 12 Years Old
    Tue, Oct 25, 2022
    Prose Writing
    Some prose I wrote for my son for his 12th birthday.
  2. Next Post
    Need SMTP? A Tutorial.
    Wed, Dec 14, 2022
    Tutorials Calckey SMTP
    Setting up SMTP to use with Calckey so you can send administrative emails.