Skip to content

Setting up Continuwuity

Perform this part on the right machine!

If you are using a VPS to bypass NAT/firewall, you do not do this on the VPS. You should do this on your home server.

Docker is the simplest way to run Continuwuity, and is generally how most people will run it. It also makes it incredibly easy to deploy in this guide. However, there are some caveats, and performance issues, so I generally advise against it. However, if you aren't confident in systems administration, or just want to get it going and never look at it again, then this Docker guide is for you.

Preparing the Docker environment

If you don't have Docker installed, run the convenience script: curl -fsSLo- https://get.docker.com | sh.

You will want to create a directory for your docker compose to live in, first off.

mkdir -p ~/continuwuity
# Then, cd into it
cd ~/continuwuity

Now you'll want to create your docker-compose.yml file. I recommend the below template as a good starting point, but there's a few of them on the official documentation site.

# this assumes docker compose that supports v3 or higher
services:
  continuwuity:
    image: forgejo.ellis.link/continuwuation/continuwuity:latest
    # If you want bleeding edge functionality, and are able to keep up with updates,
    # use the `:main` tag instead:
    # image: forgejo.ellis.link/continuwuation/continuwuity:main
    container_name: continuwuity
    restart: unless-stopped
    ports:
      - "6167:127.0.0.1:6167"  # remove 127.0.0.1 if you need to bypass the reverse proxy externally.
    volumes:
      - /etc/resolv.conf:/etc/resolv.conf:ro  # this is required to avoid DNS performance issues
      - ./config.toml:/etc/conduwuit.toml:ro
      - ./data:/var/lib/conduwuit:rw  # this is where the database and media files are stored.
      # If you want your media files to be stored on a different volume, you can instead map that like so:
      # - ./media:/var/lib/conduwuit/media:rw
      # It is recommended that the database be kept on an SSD, ideally an NVMe
      # It doesn't matter where media is stored, but the database needs to be fast. HDDs work but are suboptimal.
    environment:
      CONDUWUIT_CONFIG: '/etc/conduwuit.toml'  # tells continuwuity where the config file is

Adjust the listen address

If you have Caddy running on a different server, you will need to replace 6167:127.0.0.1:6167 with 6167:6167. This will make Docker bind to all interfaces, meaning that your external Caddy server can connect to it. If you keep it as 127.0.0.1, Caddy can only connect to it if Caddy is running on the same physical server.

Not using Docker to deploy Continuwuity is a bit more involved, but it does have some benefits. Running outside of docker generally has better performance, and can sometimes integrate with your system better (e.g. systemd, journald). However, it does require a bit more setup, and can be harder to manage.

Installing Continuwuity manually

Generally, you should look at the chapters on the docs to see distribution-specific instruction, but I'll cover the quick n dirty way to get it up and running here.

  1. Go to the latest release, and download the latest .deb file. Raspberry Pi/ARM64 users should download aarch64-linux-musl.deb, everyone else probably wants x86_64-linux-musl-haswell-optimised.deb. If you're running a CPU that is older than 2013, you will want to use x86_64-linux-musl.deb.
  2. Install the package with sudo dpkg -i <downloaded file>.
  3. Stop the service with sudo systemctl stop conduwuit.
  1. Install the continuwuity package from the AUR, using your preferred AUR helper (e.g. yay -S continuwuity). You can install the main branch version by installing the continuwuity-git package instead.
  2. Stop the service with sudo systemctl stop conduwuit.

I have no idea how to use Nix, please consult the docs, which have largely been contributed by the community.

I'll assume for the sake of simplicity that you're using systemd. If you aren't, good luck. Run the below commands as root, or with sudo.

  1. Download the latest appropriate binary from the latest release. If you're running a CPU that is older than 2013, you will want to use static-x86_64-linux-musl. Otherwise, you probably want static-x86_64-linux-musl-haswell-optimised, or static-aarc64-linux-musl if you're on ARM64.
  2. Extract the binary from the archive, and move it to /usr/local/bin/conduwuit.
  3. Download the systemd unit file from debian/conduwuit.service: 
    curl -fsSLo /etc/systemd/system/conduwuit.service https://forgejo.ellis.link/continuwuation/continuwuity/src/branch/main/debian/conduwuit.service
  4. Replace the binary location: sed -i 's|/usr/sbin/conduwuit|/usr/local/bin/conduwuit|' /etc/systemd/system/conduwuit.service
  5. Remove the "Dynamic User" setting: sed -i s/DynamicUser=true// /etc/systemd/system/conduwuit.service
  6. Reload systemd with sudo systemctl daemon-reload.
  7. Enable the service with sudo systemctl enable conduwuit. Don't start it yet!
  8. Run adduser --system --create-home --group --shell /usr/sbin/nologin --home /var/lib/conduwuit conduwuit. This will create a system user for Continuwuity to run as, and a group for it to run under.
  9. Create the config directory: mkdir -p /etc/conduwuit && chown conduwuit:conduwuit /etc/conduwuit.
  10. Download the example config file from the repo: 
    curl -fsSLo /etc/conduwuit/conduwuit.toml https://forgejo.ellis.link/continuwuation/continuwuity/src/branch/main/conduwuit-example.toml
chown conduwuit:conduwuit /etc/conduwuit/conduwuit.toml

After all that, you're done! Updating the server is as simple as downloading the latest binary, and moving it to /usr/local/bin/conduwuit, and then running sudo systemctl restart conduwuit.

Configuring Continuwuity

Now, you'll need to edit the config file. If you don't already have it (for example, you're installing with Docker), grab the latest one from the repo, and open it in your editor of choice:

# This will grab the latest config file from the repo, from the main branch.
# If you are running the latest tag, or a specific release, you should change
# the branch name to the release you are using.
# For example,
# https://forgejo.ellis.link/continuwuation/continuwuity/src/tag/v0.5.0-rc.5/conduwuit-example.toml
curl -fsSLo ./config.toml https://forgejo.ellis.link/continuwuation/continuwuity/src/branch/main/conduwuit-example.toml
$EDITOR ./config.toml

Here's the things you NEED to change:

  • server_name: This is the server name I talked about earlier. This is the bit after the : in your user ID (e.g. @user:example.com). This must be the same as the domain you registered, and the one you set up in your DNS records. Usually, this is your apex domain, e.g. example.com. YOU CANNOT CHANGE THIS AFTER YOU SET IT UP! This is also NOT your subdomain, if you set that up.
  • database_path: Set this to "/var/lib/conduwuit" (or wherever you mounted the database volume to).
  • address: Set this to "0.0.0.0"
  • ip_lookup_strategy: If you don't have IPv6, set this to 1. If you have both, just leave it as-is. Docker users should set this to 1 as docker does not support IPv6 by default.

The rest of the config can typically be left as-is, as a lot of the default values scale based on the available resources on the server.

You will also want to change trusted_servers to include a list of servers that are not matrix.org, however, they can only be Synapse servers for now. You should only set servers that you trust, but are also reliable and fast. I typically use beeper.com, envs.net, tchncs.de, and have matrix.org as a fallback.

trusted_servers = [
    "beeper.com",
    "envs.net",
    "tchncs.de",
    "matrix.org",
]

Having slow notary (trusted) servers can cause room joins to be slow, so it is recommended (but not required) to have a few of them in your config.

Creating your first user

Your first user is created by temporarily starting the server, and running the users create admin command. You only need to do this once.

To do this, run the following command:

docker compose run \
  --rm continuwuity \
  --execute 'users create <your username here> [optional password]' \
  --execute 'server shutdown'

The service must not be running when you run this command: sudo systemctl stop conduwuit.

sudo -u conduwuit conduwuit \
--config=/etc/conduwuit/conduwuit.toml \
--execute 'users create <your username here> [optional password]' \
--execute 'server shutdown'

This will create a user with the username you specified, and a password if you provided one. If you didn't provide a password, you will have to pick it out of the console output generated by the server.

The first user created will be the admin user, and will have full access to the server. You can then log in to the server with a client such as Element or Cinny, using the username you specified, and the password you provided (or the one you picked out of the console output).

I lost the password to the admin/all of my admin accounts!

If you lose the password to your admin account, you can reset it by running the following command:

docker compose run --rm continuwuity --execute 'users reset-password <your username here>' --execute 'server shutdown'

again, the service must not be running when you run this command: sudo systemctl stop conduwuit.

sudo -u conduwuit conduwuit \
--config=/etc/conduwuit/conduwuit.toml \
--execute 'users reset-password <your username here>' \
--execute 'server shutdown'

This will generate a new password for the user, and print it to the console. You can then log in with the new password. You cannot run that command while the server is running, so you will need to stop the server first.

Almost ready! Now you just need to finish setting up Caddy, and then you're good to go!