Introduction

Welcome to the Tildes Community Fork! Let's get your development environment set up.

Most of the information from the official Tildes Development docs applies here as well. Before you get too far with initial setup, read this fork's Vagrant page to see the differences when using Docker instead of VirtualBox.

The Tildes Stack

TODO!

Redis

Tips & Tricks

Entering the Redis instance can be done using redis-cli inside Vagrant or using vagrant ssh -c redis-cli directly.

Inspecting the event streams

To list all the available event streams Tildes creates you can use the following command inside Redis:

SCAN 0 TYPE stream

That will output something like this:

1) "0"
2) 1) "event_stream:comments.update.markdown"
   2) "event_stream:comment_labels.insert"
   3) "event_stream:comments.insert"
   4) "event_stream:topics.insert"
   5) "event_stream:topics.update.link"
   6) "event_stream:topics.update.markdown"
   7) "event_stream:comment_labels.delete"
   8) "event_stream:comments.update.is_deleted"
   9) "event_stream:comments.update.is_removed"

Here each of the strings starting with event_stream: correspond to one of the streams that the Tildes consumers create.

To actually see what these streams contain the XINFO STREAM <stream> command can be used, for example for the event_stream:comments.insert stream the command looks like this:

XINFO STREAM event_stream:comments.insert

Which will result in some output like this:

 1) "length"
 2) (integer) 1
 3) "radix-tree-keys"
 4) (integer) 1
 5) "radix-tree-nodes"
 6) (integer) 2
 7) "last-generated-id"
 8) "1736631555257-0"
 9) "groups"
10) (integer) 3
11) "first-entry"
12) 1) "1736631555257-0"
    2) 1) "comment_id"
       2) "34"
13) "last-entry"
14) 1) "1736631555257-0"
    2) 1) "comment_id"
       2) "34"

Vagrant

Like the official Tildes repo, this fork relies on Vagrant to setup and activate the development environment.

The development environment runs inside either a Docker container using Vagrant's Docker provider, or a virtual machine using Vagrant's VirtualBox provider. Either way, Vagrant is used from the command line to manage the virtual environment.

Most of the Development initial setup instructions from the Tildes docs apply to this fork.

This fork adds support for Docker. Docker is our preferred development environment, since the containers are more lightweight than virtual machines. However, as our Docker setup is newer, there may be a few bugs we have yet to iron out.

Docker

Running $ vagrant up --provider=docker will create an environment in a Docker container.

For more information and tips on running the Docker provider, see Docker.

VirtualBox

Running $ vagrant up without arguments will create an environment in VirtualBox, which is Vagrant's default provider.

For more information and tips on running the VirtualBox provider, see VirtualBox.

Docker

Installation

If you haven't installed Docker yet, see Docker's Getting Started page on how to install it.

Quirks

Systemd services not running after initial provisioning

Due to the way systemctl3.py monitors services, it is not able to properly monitor and restart services that (expectedly) terminate during initial provisioning.

To get services working, restart the container by running (on the host):

vagrant halt && vagrant up --provider=docker

The above should only be needed the first time provisioning a new container.

Systemd service status appears inactive

There is a known bug with systemctl3.py that causes services to incorrectly appear as "inactive (dead)" when checking their status using systemctl.

The workaround is to always use sudo when checking the status:

sudo systemctl status example.service

See also issue #13 for more discussion around some of these quirks.

File permissions errors if Git repo checked out as root on host

Don't checkout the code as root, on the host machine. It will cause file permissions errors in Docker.

VirtualBox

Notes and documentation for the VirtualBox Vagrant provider may arrive here at some point, but for now it's empty!

Development

TODO!

Miscellaneous Tools

pspg

pspg is a terminal pager built for PostgreSQl to make psql easier to use, especially useful when dealing with tables that have lots of columns. Take a look at this issue for an example before and after.

To install it you can run the following inside the Vagrant box:

# Install pspg itself.
sudo apt install -y pspg

# Set psql to use pspg as the pager.
echo 'export PSQL_PAGER="pspg -X -b"' >> "$HOME/.bashrc"

# Apply the changes in the current session. Exiting and re-entering the
# Vagrant box works too.
source "$HOME/.bashrc"

From there on any time you enter the PostgreSQL database using psql you will have a nicer pager to aid you.

Production

TODO!

Manual Provisioning of Production Machine

The Ansible playbook still does most of the heavy lifting to set up a production machine. However, before that, there are currently manual steps that need to be performed before the playbook can be run.

1. Install Debian 12, and log in as root

2. $ apt update && apt install ansible git sshpass python3-pip

3. Specify hosts in /etc/ansible/hosts (see example)

4. Create app user tildes using $ adduser tildes

5. Add tildes user to sudoers by running $ visudo and adding this line:

   tildes ALL=(ALL) NOPASSWD:ALL

6. $ ln -s /home/tildes/tildes-cf/tildes /opt/tildes

7. $ python3 -m pip install --break-system-packages -U ansible

8. $ su --login tildes

9. $ git clone https://gitlab.com/tildes-community/tildes-cf.git

10. $ cd tildes-cf

11. Set up a TLS certificate (see TLS certificate)

12. $ cp tildes/production.ini.example tildes/production.ini

13. $ ansible-playbook ansible/playbook.yml

Example Ansible hosts file

TODO: Modify the below to use SSH key instead of password

[all:vars]
ansible_user=tildes
; NOTE: Using an SSH password is insecure until we improve this provisioning procedure to use SSH keys
ansible_ssh_pass=password

[app_server]
123.123.123.123  ; replace with your server's IP

[prod]
123.123.123.123  ; replace with your server's IP

TLS Certificate

Normally a server operator should choose a high quality Certificate Authority like Let's Encrypt to acquire TLS certificates.

During testing, we can use self-signed certificates:

1. Modify ansible/playbook.yml:

Add - self_signed_ssl_cert under prod

2. Modify ansible/group_vars/prod.yml adding these lines:

ssl_cert_dir: /etc/pki/tls/certs
ssl_cert_path: "{{ ssl_cert_dir }}/localhost.crt"
ssl_private_key_path: "{{ ssl_cert_dir }}/localhost.key"

Tildes Community Fork Docs

This page is about the docs site itself (the one you're looking at), how to build it locally and how to contribute to the documentation yourself.

As you may be able to tell it is built using mdBook, picked for its ease of use and because it brings a lot of functionality out of the box.

You can install mdBook by following one of the options from the official installation guide or if you have Nix installed, a flake is available that can be used together with Direnv to automatically load a development shell.

If none of that made any sense to you but you'd still like to offer notes or add documentation, feel free to reach out using any of the following ways with your contributions and we'll take care of adding them in for you!

• Create an issue on the tildes-cf issue tracker
• Message Bauke, talklittle or Community on Tildes
• Send an email to bauke@tildes.community

Basic Usage

With mdBook installed and the repository cloned you can run the followings commands to open a live server or build the book:

# Start a live-reloading server and open your browser to the home page
mdbook serve --open

# Build the book, the output directory is "book/"
mdbook build