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