manager/README.md

   1 VM-Setup (for CI)
   2 =================
   3
   4 In the following instruction "this directory" refers to the directory (outside of the VM) where this README.md resides.
   5
   6 1. create a VM with network adapter
   7    - recommended more than 16GB HD and 1GB RAM
   8 2. install debian (stretch) into this VM
   9    - with SSHD
  10    - recommended: default user, one partition, mostly default settings
  11 3. create configuration for connecting to this vm
  12    - create an ssh-key (may have a passphrase) named "vm-key" in this directory
  13    - install the public key into the VMs authorized_keys-file (e.g. with `ssh-copy-id`)
  14    - create a file named `<myconfname>/config` containing `to=user@vm-connection-info`
  15    (steps 4 and 5 can be executed by script init-vm)
  16 4. connect to this VM and install CI-SSH-Key (generate one named vm-key in this directory)
  17    - (optional) disable SSH-Password Auth (in the VM)
  18    - (optional; required for CI) disable sudo requiring a password. (in the VM)
  19 5. (optional) install some packages for CI speedup (in the VM)
  20 6. (optional) Now may be a good time to poweroff the VM, take a snapshot and power it back on.
  21 7. run `./setup <myconfname> [fresh]`
  22    - `fresh` instructs the script to reset the VM before installing
  23
  24
  25 Creating a tricks script
  26 ------
  27
  28 You may create a script named `tricks` in this directory. This script will be executed after initial bootstrap is completed but before bootstrap-user is invoked. This script may therefore apply some site-local patches to the system to get everything ready for initializing gigi's database. Things to do here would be:
  29 - setting up additional tunnels
  30 - patching gigi's public suffix list to accept your domain
  31 - other stuff your site requires
  32
  33 Here are some useful snippets that you might want to include in your tricks file:
  34
  35
  36 ### Adding your own domain as public suffix
  37
  38 The bootstrap procedure requires Gigi’s domain to be exactly one level below a *public suffix*,
  39 for example `someca.de` or `someca.co.uk`.
  40 If you do not have many such domains to spare,
  41 you can edit Gigi’s public suffix list to add a domain controlled by you to it (for example `gigi.yourname.com`),
  42 and then run Gigi instances under `test1.gigi.yourname.com`, `test2.gigi.yourname.com` etc.
  43 In this example, `YOUR.PUBLIC.SUFFIX` below would be `gigi.yourname.com`.
  44
  45 ```
  46 if ! sudo lxc-attach -n gigi -- unzip -c /usr/share/java/gigi.jar club/wpia/gigi/util/effective_tld_names.dat | grep "YOUR.PUBLIC.SUFFIX" > /dev/null; then
  47     echo "patching public suffixes"
  48     sudo lxc-attach -n gigi -- apt-get update
  49     sudo lxc-attach -n gigi -- apt-get install --no-install-recommends -y unzip zip
  50     sudo lxc-attach -n gigi bash <<EOF
  51 cd /tmp
  52 rm -fR club
  53 unzip /usr/share/java/gigi.jar club/wpia/gigi/util/effective_tld_names.dat
  54 printf 'YOUR.PUBLIC.SUFFIX\n' >> club/wpia/gigi/util/effective_tld_names.dat
  55 zip /usr/share/java/gigi.jar club/wpia/gigi/util/effective_tld_names.dat
  56 rm -fR club
  57 EOF
  58 fi
  59 ```
  60
  61 ### Forwarding IPv6 traffic to nginx
  62
  63 All containers inside the VM have an IP address in the private 10.0.0.0/8 block,
  64 and we set up iptables rules to NAT IPv4 traffic from the VM to the nginx container
  65 (which then proxies to Gigi).
  66 This doesn't work if your VM only has a public IPv6 address, for example because its host system is on a residential connection.
  67 In this case, you can set up another server (with an IPv4 address) to proxy to your system via IPv6,
  68 and then run services in the VM that forward that IPv6 traffic back to nginx' IPv4 address.
  69 (You will have to use that server's domain name in your configuration,
  70 and possibly adjust the public suffix list as described elsewhere in this document.)
  71
  72 ```
  73 if ! [[ -f /etc/systemd/system/forward-to-nginx@.socket ]]; then
  74     sudo tee /etc/systemd/system/forward-to-nginx@.socket > /dev/null << 'EOF'
  75 [Unit]
  76 Description=Listen on port %i and forward it to the nginx container
  77
  78 [Socket]
  79 ListenStream=%i
  80
  81 [Install]
  82 WantedBy=sockets.target
  83 EOF
  84     sudo systemctl daemon-reload
  85 fi
  86 if ! [[ -f /etc/systemd/system/forward-to-nginx@.service ]]; then
  87     sudo tee /etc/systemd/system/forward-to-nginx@.service > /dev/null << 'EOF'
  88 [Unit]
  89 Description=Forward port %i to the nginx container
  90 Documentation=man:systemd-socket-proxyd(8)
  91
  92 [Service]
  93 ExecStart=/lib/systemd/systemd-socket-proxyd 10.0.3.13:%i
  94
  95 DynamicUser=yes
  96 PrivateUsers=yes
  97 PrivateTmp=yes
  98 PrivateDevices=yes
  99 ProtectSystem=strict
 100 ProtectHome=yes
 101 NoNewPrivileges=yes
 102 SystemCallArchitectures=native
 103 RestrictAddressFamilies=AF_INET
 104 ProtectKernelModules=yes
 105 MemoryDenyWriteExecute=yes
 106 RestrictRealtime=yes
 107 EOF
 108     sudo systemctl daemon-reload
 109 fi
 110 sudo systemctl enable forward-to-nginx@{80,443}.socket
 111 sudo systemctl start forward-to-nginx@{80,443}.socket
 112 ```
 113
 114
 115 Other snippets
 116 --------------
 117
 118 ### Restarting the user-bootstrap procedure
 119
 120 If you entered wrong bootstrap users or something went wrong during the final phase of bootstrapping
 121 (the actual initialization of Gigi’s database with the first administrative accounts)
 122 you can kill the script and then wipe the database with the following one-liner (run in the VM):
 123
 124 ```bash
 125 sudo lxc-attach -n gigi -- systemctl stop gigi-proxy.{service,socket} cassiopeia-client && sudo lxc-attach -n postgres-primary -- su -c "psql" postgres <<< "DROP DATABASE gigi; CREATE DATABASE gigi;"
 126 ```
 127
 128 Afterwards, you can run `./bootstrap-user` in the VM again.