Hacklab IT Infra documentation

Jitsi (from Bulgarian: жици — "wires") is a collection of free and open-source multiplatform voice (VoIP), video conferencing and instant messaging applications for the Web platform, Windows, Linux, macOS, iOS and Android.

https://jitsi.hacklab.fi

Hacklab.fi Matrix general instructions

What?

Matrix is versatile federated instant messaging protocol and we offer Matrix homeserver and services to Finnish hacklab members.

Matrix also supports bridges, both puppeted and relaybot, to various other networks and systems, like IRC, Telegram, Whatsapp, SMS, etc for example.

General about matrix terminology
Registering an user
Clients
Login
Bridges

General about matrix terminology

MXID

Matrix user id is called MXID, and it constructs from username and domain part, which are inseparable. This means that where ever in you need to input your MXID it should be in format: @example:hacklab.fi

User domain

User domain is the designated domain name in MXID, in our case hacklab.fi

Homeserver

Homeserver is the matrix-server catering hacklab.fi users, in our case matrix.hacklab.fi

Users, rooms and spaces

In Matrix usernames allways starts with @ -sign, rooms an spaces with # -sign

Registering an user

Primary method:
- Surf to hacklab.fi Element login and select Continue with Hacklab Finland Keycloak
- Your local Hacklab should have implemented Single Sign-On method that is used by our Matrix-server login-flow, if not, nag them hard ;)
- after SSO-autorization figure an username and continue
Secondary method, eventually obsoleted:
- Surf to hacklab.fi Matrix user registration website
- Fill out your details
  - Figure an username (only name, no domain here)
  - Figure out password
  - Provide an known Invite token, this can be acuired from your Hacklab
- Press register

Clients

There are many clients programs for diffirent platforms and personal tastes available. Reference client is Element, which is available for computers, phones and we also offer an web-instance at https://chat.hacklab.fi

Most matrix clients supports automatic discovery of server settings when you give your full MXID as username, so often times it is enough to type in the @example:hacklab.fi as username and your password.

If manual server settings are needed, they are:

Homeserver URL: https://matrix.hacklab.fi
Identity Server URL: blank/none

Bridges

Matrix has awesome integration for various other Chat/IM networks and services, called bridges, which makes using matrix an killer thing. IRC is offered pretty much baked in into Matrix, and for finnish Hacklab members we offer also bridges for Telegram, Whatsapp and SMS. There is also on-going effort to offer Slack bridging, and more can be added if installable bridge-services exists.

Hacklab member using hacklab.fi homeserver, thus having MXID of @user:hacklab.fi, has automatic access to use bridges trough hacklab.fi servers, hacklab members using some other homeserver need to ask to be added into bridge(s) manually, ask more in Matrix channel: #general:hacklab.fi

Links to specific bridge instructions in navigation sidebar, below some that has not been yet documented by us, but are in use:

IRC:
- Heisenbridge: https://github.com/hifi/heisenbridge
- Appservice-irc (run by others!): https://github.com/matrix-org/matrix-appservice-irc/wiki

Other useful tools

Hookshot (Bot for connecting to external services like GitHub, GitLab, JIRA, general webhooks)

Historical / deprecated:

SMS: We used to have "smsbot", doesn't scale and was impossible to setup without admin involvement.
Appservice-slack: Buggy and impossible to maintain, Mautrix-slack replaced this.
MX-puppet-discord: EOL, Mautrix-discord replaced this.

Matrix<->Discord bridge

What?

An Matrix<->Discord bridge for receiving and sending Discord messages with Matrix-client.

Set up

Get Power Level 50 in Matrix room (not sure why bridge wants that..)
You also need to be admin at Discord channel or have a admin to help you
Get a invite link from one of Hacklab.fi admins at #matrix:hacklab.fi. Don't spread the link as it can be used to invite the bot to any Discord room.
Invite the bridge to your Discord server using the link. The bridge will need all the permissions selected.
Invite @_discord_bot:hacklab.fi to your Matrix room. The bot should have permissions to invite users.
Open the text channel you'd like to bridge in the Discord web application.
In the address bar there should be a URL like https://discordapp.com/channels/ServerID/ChannelID
Use that as a reference to say in your Matrix room !discord bridge ServerID ChannelID
The bridge will ask for confirmation on Discord side, and after approved your room should be bridged to Discord.

Matrix<->Facebook bridge

This instance uses Mautrix-Meta software

Up to date info about bridge itself: https://docs.mau.fi/bridges/go/meta/index.html

What?

An Matrix<->Facebook chat bridge for receiving and sending Facebook chat messages with Matrix-client.

Set up

There are two flavours of this bridge, here are their main differences:

@facebookbot

Uses facebook.com, requires user to have activated Facebook account, but works without any additional software needed at setup time.

@messengerbot

Uses messenger.com, allows user to have deactivated Facebook account and still use Facebook Messenger, but needs Messenger phone application at least once to succeed.

Logging in

Open chat with either @messengerbot:hacklab.fi or @facebookbot:hacklab.fi based on your flavour of bot
Send login
Follow any instructions bot gives.
Recent chats should now get portals automatically. Other chats will get portals as you receive messages.

Double puppeting

For hacklab.fi homeserver users this bridge does double-puppeting automatically.

Note

Info taken and adapted to our use from Mautrix-meta wiki, so in case of info gets outdated, try refer there.

Matrix<->Instagram bridge

This instance uses Mautrix-Meta software

Up to date info about bridge itself: https://docs.mau.fi/bridges/go/meta/index.html

What?

An Matrix<->Instagram chat bridge for receiving and sending Instagram chat messages with Matrix-client.

Set up

Logging in

Open chat with @instagrambot:hacklab.fi
Send login
Follow any instructions bot gives.
Recent chats should now get portals automatically. Other chats will get portals as you receive messages.

Double puppeting

For hacklab.fi homeserver users this bridge does double-puppeting automatically.

Note

Info taken and adapted to our use from Mautrix-meta wiki, so in case of info gets outdated, try refer there.

Matrix<->Google Messages bridge

Up to date info about Mautrix-gmessages itself: https://docs.mau.fi/bridges/go/gmessages/index.html

What?

An Matrix<->Google Messages bridge for receiving and sending Google Messages (both SMS and RCS) with Matrix-client, Pairs with Google Messages app included in most Android phones, also installable from Play-store.

Special notes

This bridge uses the GMessages API, so your phone must be connected to the internet for the bridge to work. This is not stand alone bridge.

Set up

Start a chat with the bridge bot @gmessagesbot:hacklab.fi. The bot should say "This room has been registered as your bridge management/status room." if you started the chat correctly.
Write login to the room.
Log in by scanning the QR code with Google Messages app. If the code expires before you scan it, the bridge will send an error to notify you.
- Open Google Messages on your phone.
- Tap Burger-menu and select Device pairing.
- Tap "QR code scanner" -button.
- Point your phone at the image sent by the bot to capture the code.
Finally, the bot should inform you of a successful login and the bridge should start creating portal rooms for all your SMS and RCS "chats".

Double puppeting

For hacklab.fi homeserver users this bridge does double-puppeting automatically.

Matrix<->Signal bridge

Up to date info about Mautrix-signal itself: https://docs.mau.fi/bridges/go/signal/index.html

What?

An Matrix<->Signal bridge for receiving and sending signal messages with Matrix-client, bridging groupchats, puppeting.. Using as linked device (signal stuff), direct messaging and group chats.

Set up

On matrix: Open chat with @signalbot:hacklab.fi
Issue login to link the bridge as a secondary device
Follow instructions bot tells you

You can use your Signal app on an phone as your primary device, or run Signal app in Virtual Android, or there is also 3rd alternative: signal-cli, which usage is explained out in Mautrix-signal wiki

Double puppeting

For hacklab.fi homeserver users this bridge does double-puppeting automatically.

Note

Info taken and adapted to our use from Mautrix-signal wiki, so in case of info gets outdated, try referring there.

Matrix<->Slack bridge

Up to date info about Mautrix-slack itself: https://docs.mau.fi/bridges/go/slack/index.html

What:

An puppeting Matrix<->Slack bridge for receiving and sending Slack messages with Matrix-client, has relaybot possibility.

Set up

Start a chat with the bridge bot @slackbot:hacklab.fi. The bot should say "This room has been registered as your bridge management/status room." if you started the chat correctly.
- Write help to see all commands and options available to you.
Write login to the room.
Follow on-screen instuctions
If something doesn't work, up to date details finds from: https://docs.mau.fi/bridges/go/slack/authentication.html

Double puppeting (recommended)

For hacklab.fi homeserver users this bridge does double-puppeting automatically.

Matrix<->Telegram bridge

Up to date info about Mautrix-telegram itself: https://docs.mau.fi/bridges/python/telegram/index.html

What?

An Matrix<->Telegram bridge for receiving and sending Telegram messages with Matrix-client, bridging groupchats, puppeting, relaybot... Full integration.

Set up

For using own Telegram through Matrix:

On Matrix: Open chat with @telegrambot:hacklab.fi
help gives you available commands, usually start with login
There is multiple ways of using and commanding the bot, so refer Mautrix-telegram wiki

Double puppeting

For hacklab.fi homeserver users this bridge does double-puppeting automatically.

For bridging Matrix channel to Telegram group:

On Matrix: Invite @telegrambot:hacklab.fi to Matrix-room to be bridged
On Telegram: invite @hacklabbridgebot to channel
On Matrix: Get the ID of the Telegram chat with the !tg id and the Telegram-bot should answer with group ID.
On Matrix: Run !tg bridge <chat ID> in the room you want to bridge.
Refer Mautrix-telegram wiki for detailed up to date instructions

Matrix<->Whatsapp bridge

Up to date info about Mautrix-whatsapp itself: https://docs.mau.fi/bridges/go/whatsapp/index.html

What?

An Matrix<->Whatsapp bridge for receiving and sending Whatsapp messages with Matrix-client, purely for bringing your personal Whatsapp to your Matrix-client, does have relaybot support.

Special notes

This bridge uses the web API, so your phone must be connected to the internet for the bridge to work. The WhatsApp app doesn't need to be running all the time, but it needs to be allowed to wake up when receiving messages (should work by default). The web API is used instead of the main client API to avoid bans (WhatsApp will ban unofficial clients).

There also exist instructions how to run Android in virtual machine so you could get rid of Whatsapp alltogether from your actual phone, read more at Mautrix-whatsapp wiki, Android VM Setup

Set up

Start a chat with the bridge bot @whatsappbot:hacklab.fi. The bot should say "This room has been registered as your bridge management/status room." if you started the chat correctly.
- To log in by entering a 8-letter code on your phone, enter: login +358123456789.
- To log in by scanning the QR code, enter: login. If the code expires before you scan it, the bridge will send an error to notify you.
Open WhatsApp on your phone.
Tap Menu or Settings and select Linked devices.
- Log in by QR-code: Point your phone at the image sent by the bot to capture the code.
- Log in with pairing code: Tap "Link with a phone number instead".
Finally, the bot should inform you of a successful login and the bridge should start creating portal rooms for all your WhatsApp groups and private chats.

Double puppeting (recommended)

For hacklab.fi homeserver users this bridge does double-puppeting automatically.

Matrix Hookshot

Github, Gitlab, Jira and generic webhooks!

https://matrix-org.github.io/matrix-hookshot/latest/hookshot.html

https://github.com/matrix-org/matrix-hookshot

What?

A Matrix bot for connecting to external services like GitHub, GitLab, JIRA, and more.

Usage

At the moment webhooks, feeds and github are supported.

bot user is @hookshot:hacklab.fi admins are @tsw:hacklab.fi and @olmari:hacklab.fi

command: hookshot help gives you basic information of things

webhooks

Invite @hookshot:hacklab.fi to your channel, give it moderator rights and ask it to add a webhook endpoint for you

/invite @hookshot:hacklab.fi
/op @hookshot:hacklab.fi 50
!hookshot webhook [nameforyourwebhook]

See the endpoint url from the admin room and send a test message to it:

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{"username": "its a me mario", "text": "yup, message from webhook", "html": "<i>yup</i><h2>formatting</h2>"}' \
  https://matrix.hacklab.fi/hookshot/webhook/REDACTED

To delete a webhook

feeds

Invite @hookshot:hacklab.fi to your channel, give it moderator rights and ask it to add a webhook endpoint for you

/invite @hookshot:hacklab.fi
/op @hookshot:hacklab.fi 50
!hookshot feed https://example.com/feed/atom/ [nameyourfeed]

To list existing feeds

!hookshot feed list

And to remove a feed

!hookshot feed remove https://example.com/feed/atom

github

Github has a github app registered for us Hacklab.fi Matrix Hookshot to use for the integration (@tsw:hacklab.fi, github username tswfi is the owner)

Install the app https://github.com/apps/hacklab-fi-matrix-hookshot into your account / organisation you want to use with hookshot.

To login to your github account talk with @hookshot:hacklab.fi and check with github status if you are already logged in and with github login you can complete oauth with github.

Then in your channel you can bridge a github project to your room with !hookshot github repo https://github.com/my/project. If the connection is done successfully you will get a confirmation and you can start choosing what you want to get notified about.

Now that the channel is bridged to the repo you can use some commands to update issues and so on

Creating new issue

!gh create "Title text" "Description for the issue" "label1,label2"

You can omit the labels (but its best to always have some description)

Closing an issue

!gh close 3 "Yay, great job!"

Hookshot github app will also push changes to the channel. Managing what to show is defined in the room state. TODO: document how to change these:

Check all the available options in https://matrix-org.github.io/matrix-hookshot/latest/usage/room_configuration/github_repo.html#configuration

Misc

Telegram bot entity

For Telegram side there exist bot with userhandle @HacklabFiHookshotBot that is tied into this Hookshot matrix-bot entity. Its purpose is to provide an actual user for Hookshot messages in matrix-room that is bridged to Telegram.

Bot is configured as "passive" bot, it has no reading rights inside Telegram room, it's purely echoing what hookshot says in matrix side in bridged room.

To utilize this all that is needed to do is to add the bot into the bridged Telegram room in Telegram side.

How it was installed

Running on our matrix server under user matrix-hookshot, home directory in /opt/matrix-hookshot.

Requires at least Node 16 and Rust installed. Those are installed via nvm and rustup. The base requirements for those are

sudo apt update && sudo apt upgrade
# rustup
sudo apt install curl build-essential gcc make
# node
sudo apt install build-essential libssl-dev

basic steps for creating the user, installing necessary stuff and so on (note, the curl commands are taken from https://github.com/nvm-sh/nvm#installing-and-updating and https://rustup.rs/)

Create user

# create user
sudo useradd --shell /usr/sbin/nologin --system --user-group --create-home --comment "Matrix Hookshot" --home-dir /opt/matrix-hookshot matrix-hookshot

Install node

# become the user
sudo -Hu matrix-hookshot /bin/bash -l
# install nvm and rustup
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
# logout and relogin to load nvm
logout
sudo -Hu matrix-hookshot /bin/bash -l
# install node 20 (latest LTS as of writing this 20231110)
nvm install 20
# logout and relogin to load nvm with the new default node 20 config
logout
sudo -Hu matrix-hookshot /bin/bash -l
# check that node works
node -v
logout

the node -v command should output something like v20.9.x

install rustup

# become the user
sudo -Hu matrix-hookshot /bin/bash -l
# start rustup installation
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# and logout login to activate the profile
logout
sudo -Hu matrix-hookshot /bin/bash -l
# and check that you have rust
rustc -V
logout

The rustc -V command should output something like rustc 1.xx.xx (xxxxxx yyyy-mm-ddd)

now we can setup the bot

# become the user
sudo -Hu matrix-hookshot /bin/bash -l
npm install -g yarn
cd
git clone https://github.com/matrix-org/matrix-hookshot.git
cd matrix-hookshot
yarn

And wait while it fetches few gigs of node-modules and compiles the rust stuff

Configurations

Basically copy the registration.sample.conf and configuration.sample.conf to registration.conf and configuration.conf and change all the settings.

For this instance the configuration files can be found from the server and backups in the home directory of matrix-hookshot

appservice conf (aka registration.sample.conf or registration.conf)

on our server all the appservice configurations are collected in /etc/matrix-synapse/app_service_config_files/. the file in the matrix-hookshot folder also as the service will read it too.

so always modify the registration.yml and then copy it to into /etc/matrix-synapse/app_service_config_files/matrix-hookshot.yml

sudo cp /opt/matrix-hookshot/matrix-hookshot/registration.yml /etc/matrix-synapse/app_service_config_files/matrix-hookshot.yaml
sudo chown matrix-synapse:matrix-synapse /etc/matrix-synapse/app_service_config_files/matrix-hookshot.yaml
sudo chmod 600 /etc/matrix-synapse/app_service_config_files/matrix-hookshot.yaml

And reload matrix-synapse after modifications.

nginx conf

add two new location blocks

        # hookshot
        location /[YOUR]/ {
                include snippets/matrix-proxy-headers.conf;
                include snippets/matrix-proxy-headers-client.conf;
                proxy_pass http://localhost:[PORT]/;
        }
        location /[YOUR]/oauth {
                include snippets/matrix-proxy-headers.conf;
                include snippets/matrix-proxy-headers-client.conf;
                proxy_pass http://localhost:[PORT]/oauth/;
        }
        location /[YOUR]/[PREFIX]/ {
                include snippets/matrix-proxy-headers.conf;
                include snippets/matrix-proxy-headers-client.conf;
                proxy_pass http://localhost:[PORT]/webhook/;
        }
        # end hookshot

where [YOUR]/[PREFIX] is what you defined in config.yml and port is the port you defined in config.yml for webhooks

And /[YOUR]/ is something that you can choose. Values hookshot and webhook are quite obvious choices.

unit file

add unit file for this service

[Unit]
Description=Matrix Hookshot
After=matrix-synapse.service

[Service]
Type=exec
User=matrix-hookshot
WorkingDirectory=/opt/matrix-hookshot/matrix-hookshot
Environment=NODE_VERSION=20
ExecStart=/opt/matrix-hookshot/.nvm/nvm-exec yarn start
Restart=on-failure
RestartSec=60s

[Install]
WantedBy=multi-user.target

start everything

first validate hookshot the config in $HOME/matrix-hookshot with

yarn validate-config

Then:

restart synapse to get the new appservice onboard
restart nginx to get the proxy configuration
restart matrix-hookshot to restart the bridge

secrets

check secrets in the users home folder

Peertube

Under construction, see https://github.com/hacklab-fi/itinfra/issues/23

Sysops

We have range of services and servers running all of this.

Upcloud

We have few servers running on upcloud (thanks, we love you <3 !!!)

If you are considering using upcloud service, please you use this link to order: https://upcloud.com/signup/?promo=hacklab

If you need access to the servers ask Sami Olmari or Tatu Wikman

Creating new system user for daemons and bots etc

We use /opt/ for base home folder for system users, give it nologin as shell, etc

sudo useradd --shell /usr/sbin/nologin \
  --system --user-group \
  --create-home \
  --comment "Service longname" \
  --home-dir /opt/servicehomedir username

Getting shell as system user for admin to do thing as the user

sudo -Hu username /bin/bash -l

Same can be used to run psql on postgres user directly

sudo -Hu postgres psql

Software installations

We've used apt repositories where possible and rest is "directly on the host" installations, following given documentation per bot or automaton, provides update instructions too

Links to most of them:

mautrix-bridges: https://docs.mau.fi/bridges/index.html
heisenbridge: https://github.com/hifi/heisenbridge
Appservice-irc: https://github.com/matrix-org/matrix-appservice-irc/wiki

We allow only publickey auth and user needs to belong into ssh-user group in order to connect into server with SSH

SSH server related settings resides in /etc/ssh/sshd_config.d/ "confd" directory, edit settings in files under that dir and not directly /etc/ssh/sshd_config file. Same goes for possible client settings (ssh_config.d/).

DNS resolving

We run Bind9/named as resolving DNS-server to provide credible DNSSEC resolving and OCSP-stapling.

If you need to define DNS-server to some service, use localhost or it's IP-variations 127.0.0.1 and ::1.

Github

Github is used for quite a few things

https://github.com/hacklab-fi

Ask to join the organization and start making hacking on websites and this documentation!

GCP

Google Cloud Platform

We have mainly DNS running on Google Cloud Platform

DNS

hacklab.fi zone lives in GCP Cloud DNS

Sami Olmari and Tatu Wikman can help with setting up your city zone

Thanks

Thanks to all the hackers that make this possible!!