|southerntofu 8d3b7e29a6||4 weeks ago|
|.common||1 month ago|
|.debian/tasks||1 month ago|
|.go/tasks||1 month ago|
|.rust/tasks||1 month ago|
|chatbridge||1 month ago|
|jabberserver||4 weeks ago|
|mailserver||1 month ago|
|tls||1 month ago|
|tor||1 month ago|
|webserver||4 weeks ago|
|LICENCE||1 month ago|
|README.md||4 weeks ago|
|deploy.sh||1 month ago|
|main.yml||1 month ago|
WARNING: This is a codename and will change.
In this repository, you will find all you need to setup your own server. It contains:
To configure your server, you will need a dedicated folder to keep track of all the configuration. It is recommended to version this folder with git or mercurial (or the tool of your choice). This repository should then be cloned as a submodule in the
roles folder. Assuming you want to store server data in
/etc/server, you could do:
# mkdir /etc/server; cd /etc/server # git init # git submodule add https://codeberg.org/southerntofu/ansible-selfhosted /etc/server/roles
Now, you should:
Your server configuration folder should look like this in the end:
We currently support the following high-level services:
webserver(docs, todo): setup static websites (with git source and build command) or reverse proxies, with automatic TLS/Tor support
mailserver(docs, todo): setup mailboxes and aliases, with automatic TLS/Tor support
jabberserver(docs, todo): setup MUC servers and/or anonymous/guest vhosts, with automatic TLS/Tor support
chatbridge(docs): a bot to bridge connections across instant messaging networks (IRC, Matrix, Jabber/XMPP) such as matterbridge
Some roles are intended as building blocks for other roles, though they may come in handy in specific situations:
tls: request a TLS certificate from letsencrypt for a domain, and optionally some aliases (docs, todo)
tor: setup a Tor onion service acting as a reverse proxy for a local service (docs, todo)
Some additional roles we'd like to support in the future:
nameserver: setup primary/secondary DNS server
There is also some roles acting as package managers, as explained later in this document.
The configuration file from the server is
config.yml. In addition to specific role configuration, there's a number of high-level settings in there, explained in this section.
In order to operate properly, the server needs a certain number of base settings:
hostname: the main domain name for the server
aliases: a list of domain names also vaild for this server, which will be included in the main TLS certificate
contact: contact information used by some roles
xmpp_muc: a list of Jabber/XMPP chatrooms (default:
xmpp_users: a list of Jabber/XMPP users (default:
TODO: Package managers should be better documented and their interface standardized. WTF does go not accept https://github.com/ as valid repository source and require to strip the scheme?
The configuration file contains a
packages field, which is a mapping of package managers to a list of packages for them to install. How the list of packages is treated may be different for every package manager. For example:
packages: debian: [ "tmux" ] rust: - "lsd" - bin: "zola" repo: "https://github.com/southerntofu/zola" version: "bugfix-index-translations"
This configuration snippet above will setup three packages:
Internally, every package manager is a role prefixed by a dot, to avoid confusion with other roles (services). We currently support the following package managers:
.common is a reserved role name, and cannot be used for a
common package manager.
The configuration file has a
services field, which is a list of services (roles) to setup on the server. In most cases, it should contain the
.common role, which will perform the base setup. For example:
services: - ".common" - "webserver"
This snippet above will configure the base server, as well as a webserver. The webserver configuration, like any other service configuration, is kept in a separate field so the services remains human-readable. The field containing the configuration for a specific service wears the same name as the service (role) itself. For example, webserver configuration lives in a
webserver field in the configuration file. Inside a service configuration, global settings are usually defined in a
settings key, for example
Most services can be configured to serve different domains/users. These specific configuration blocks are separated into what we call virtualhosts, or vhosts for short. Each such vhost for a service is configured in the
vhosts list, inside the service configuration block. For example,
webserver.vhosts. How to configure a vhost for a specific service is left to interpretation, and you should refer to service docs in order to find out what kind of settings a vhost may accept/require, and what the service will do with those settings.
Note: Some services may use similar concepts, though not called "vhosts". For example,
chatbridge service uses
chans for multiple configurations.
A service may support different use-cases for each vhost. While these are usually defined using the
template setting of a vhost, we provide a high-level shorthand method for defining separate profiles without typing it out for each individual vhost. Each service profile is a top-level configuration key inside the service configuration, wearing the name of the service profile, and containing a list of vhosts which will be loaded with
template set to this profile name. Take the following configuration snippet:
webserver: vhosts: - host: "example.org" template: "static" git: "https://git.example.org/foo/bar" - host: "example.net" template: "static" git: "https://git.example.net/foo/bar"
The above snippet is strictly equivalent to:
webserver: static: - host: "example.org" git: "https://git.example.org/foo/bar" - host: "example.net" git: "https://git.example.net/foo/bar"
A deploy.sh script is provided to make deploying easier. It's intended to be run as root from the server itself, and optionally accepts positional arguments representing a list of services to (re)configure, instead of following the services list defined in the configuration file:
# # Setup the server according to config.yml # ./deploy.sh # # Only reconfigure webserver # ./deploy.sh webserver
This document is the top-level documentation. In addition, you may find documentation about:
This project is protected by AGPLv3 license. We believe the fruit of human labor should belong to humanity as a whole, and privatization of resources and knowledge is harmful. If you don't have time to read the full license, you may: