Installing

Compatibility

These are the tested GNU/Linux distributions. Maybe it works on some other distributions too or just requieres a few changes.

• debian
  • stretch

Requeriments

First of all on remote server:

1. Install sudo and python.
2. Login as root and add your user to sudoers or to the sudo group with usermod -a -G sudo [user].

Installing

For installing Whiteclub’s ansible playbook with the roles, type:

$ git clone --recursive https://github.com/anarres-org/anarres.git

Whiteclub ansible roles are:

• anarres-nginx: Ansible role to install, configure and launch Nginx.
• anarres-common: Ansible role to install and configure some basic utilities for a GNU/Linux server.
• add_nginx_proxy_conf: This role adds and enables a reverse proxy configuration to an existing nginx instance.
• anarres-sec: Ansible role for basic GNU/Linux server hardening.
• generic_docker_systemd: Creates a systemd unit file that manages a docker image.

Usage

Before running the ansible playbook on a server, it is (very) recommended to test it with molecule. See Testing for more info.

For deploying Whiteclub on a remote server, we need to specify our server variables. Default variables are on group_vars/all.yml. You can create a custom/ folder in the playbook root directory. There you can save your inventory files with your chosen variables for each host. This folder will be ignored by .gitignore.

As some of the variables are passwords, you can encrypt them with ansible-vault

An example of a custom inventory, stored on /custom/[project]/hosts.yml:

ea4rct:
  hosts:
    delta:
      ansible_sudo: true
      ansible_port: 666
      ansible_host: radio.clubs.etsit.upm.es
      become: true
      user_uid_1000: delta
      base_domain: radio.clubs.etsit.upm.es
      ssh_port: 666
      db_pass: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          64383763323966383636613365363538356335616562383066396166643930623233363533326234
          31633361356263643061643565313532626363383266666790a653535396236333963323736366539
          37386132633231656564633362386134326239336635356364386235613239643263663533303562
          6539613761353634620a303532656166663634323433663739666336343739646435316435623363
          65646430326136353437306465336437343965386162356638303238313264356536
      gitea_ssh_port: 22
      gitea_db_user_pass: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          64643061353638306236333364633962653435666438636561393062376262363061336565303332
          3236353034376433303631376430356434636161653436370a396639636234623433653133353466
          36346534316361613635306531623337626532653565313099943262343535656466366531633835
          3639333766313164300a363830613063326636373531653534616434613333346436646235336230
          31653935353161663034666336653662636635303633326438326662346632636439
      openvpn_domain: "{{ base_domain }}"
      openvpn_ca_pass: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          34396265393666306430653139373437323532386363373264323165346264626661636230616665
          3665363065663535303663343434633737643264613439610a663965613136393036623330356164
          37623564343233656338396533343464633533333964349966396231356335376633316334636631
          3030323737313462300a633130373463346535353833333634326566613833303433323461383730
          62396166343165376236346563383339346336306333656434643932663961636365

For encrypting variables with ansible-vault see Use encrypt_string to create encrypted variables to embed in yaml.

Running an ansible-playbook is as follow:

ansible-playbook -i custom/[project]/hosts.yml full.yml -u USER --become --ask-become-pass --ask-vault-pass -t "TAG1, TAG2..."

On the other hand, if you want to skip some tags:

ansible-playbook -i custom/[project]/hosts.yml full.yml -u USER --become --ask-become-pass --ask-vault-pass --skip-tags "TAG1, TAG2..."

The idea is that you run the playbooks with the tags of the services that you want to setup. But, there are some steps that “must” be run first, before deploying the actual services.

An example approach would be:

1. Deploy the basic stuff (dependencies, directory creation, security…): -t init,common,sec
2. If everything goes well, deploy the base web server: -t web
3. Now you are ready to deploy the desired services, for example gitea: -t gitea

Tips

• You can check the available tags with: bash $ ansible-playbook --list-tags full.yml
• You can create a custom/ folder in the playbook root directory. There you can save your inventory files with your chosen variables for each host. This folder will be ignored thanks to the .gitignore configuration.
• As some of the variables are passwords, you can encrypt them with ansible-vault
• Before deploying anything, check the variables and their default values from group_vars/all.yml. Copy and change the required ones to your custom inventory file.
• Deploy only a few tags with: bash ansible-playbook -i custom/[project]/hosts.yml full.yml --extra-vars ansible_become_pass="[sudo_password]" --ask-vault-pass -t gitea

Variables

Whiteclub ansible playbook default variables are on group_vars/all.yml. Main variables are:

• user_uid_1000: First user on the server.
• base_domain: Base domain of the server.
• ssh_port: SSH will be configured on this port. For security reasons select a high port (like 6666)
• db_pass
• gitea_ssh_port: Recommended to be 22 (so ssh must be on other port).
• gitea_db_user_pass
• gitea_domain: Default is git.{{ base_domain }}
• drone_domain: Default is drone.{{ base_domain }}
• openvpn_domain
• openvpn_ca_pass
• openldap_organization
• openldap_base_DN
• openldap_admin_password
• openldap_readonly_password

Firewall

If you are behind some kind of firewall or you need to setup NAT, you should add the following ports:

• 80 for HTTP connections, used for the letsencrypt verification
• 443 for HTTPs connections, used by the reverse proxy to serve access to the web services.
• The SSH port you choose, or 2222 by default.
• All the desired ports that some services have.

Services

Their data and configuration files will be stored in your hosts data_path directory, by default /data.

Letsencrypt

The main domain cert needs to be obtained using the standalone method since we don’t have a working webserver by this point (the server needs the cert). So the webroot path will be empty in /etc/letsencrypt/renewal/{{ base_domain }}.conf. You should manually specify it adding:

authenticator = webroot
webroot_path = /var/www/letsencrypt,

Gitea

First user to register will be the admin user.

Ports: 22/tcp for SSH.

Drone

Continuous integration configured for gitea.

Ports: 443.

Hackmd

Online Markdown editor.

Ports: 443.

OpenVPN

Once installed, from the server’s command line.

Ports: 1194/udp.

Genereate new user keys

docker exec -it openvpn easyrsa build-client-full [USERNAME] nopass

Get the configuration file for an existing user

docker exec -it openvpn ovpn_getclient [USERNAME] > [USERNAME].ovpn

Syncthing

Make sure to set up a user and password for the web GUI. You can do that by accesing it ang going to settings.

Ports: 22000/tcp as the listening address and 21027/udp for local discovery.

Tranmission

It’s recommended to enable port forwarding in your router as explained in superuser. The default port is 51413 but you can change this from the web configurations.

If you don’t set tranmission_user and transmission_pass you’ll need to edit settings.json as explained in hub.docker.com

Ports: 51413 tcp and upd for p2p connections.

Radicale

You must set radicale_pass with your bcrypted password. Yo can get the hash by running:

htpasswd -B /tmp/radicale [user]

Get it from /tmp/radicale.

Taskd

The taskwarrior server.

Ports: 53589/tcp.

Open a shell in the container.

docker exec -it taskd /bin/sh

And then from inside the container run the commands from the taskwarrior docs.

Note: The pki directory is in /var/taskd/pki/

Nextcloud

First user to register will be the admin user.

NFS

Please refer to ubunut-help to see how NFSv4 works. Make sure to mount the directories you want to export inside the /export folder of the NFS container. Mount them with the :ro option if you want them to be read-only (and configure them in the exports conf accordingly).

Ports: 2049/tcp.

OpenLDAP

An OpenLDAP server for the internal services.

Ports: 636/tcp.

phpLDAPadmin

A web interface for managing OpenLDAP.

BIND DNS server

You need to specify the user with the uid 101 if it isn’t systemd-network. Check it in /etc/passwd.

Refer to ubuntu-help to see how to configure it.

Ports: 53/tcp and 53/udp.

Backup

Make sure to backup your data_path (by default /data) and the docker volumes (used by the databases) from /var/lib/docker/volumes.