ansible-infra/docs/guides/web-service-setup.md

title	summary
Web Service	How to Setup a Web Service

Web Service

This guide assumes you followed New Chaosknoten VM for setting up a VM (myservice) in the v4-NAT network. It continues of that to set up a web service mywebservice behind our public-reverse-proxy.

1. First, the public-reverse-proxy should be configured to make the upcoming web service reachable and have certbot work.
   1. Start out by adding an entry to the map in the stream section in playbooks/resources/chaosknoten/public-reverse-proxy/nginx/nginx.conf, e.g.:

   stream {
       # ...
       map {
           # ...
           mywebservice.hamburg.ccc.de myservice.hosts.hamburg.ccc.de:8443;
       }
   }
   

   2. Next add an entry to the map in playbooks/resources/chaosknoten/public-reverse-proxy/nginx/acme_challenge.conf, e.g.:

   map $host $upstream_acme_challenge_host {
       # ...
       mywebservice.hamburg.ccc.de myservice.hosts.hamburg.ccc.de:31820;
       default "";
   }
   

   3. Finally apply the configuration by running the Ansible playbook for the public-reverse-proxy:

   ansible-playbook playbooks/deploy.yaml -i inventories/chaosknoten/hosts.yaml -l public-reverse-proxy -t public_reverse_proxy
   

2. Add a CNAME for the FQDN of the service pointing to the public-reverse-proxy. For a service myservice under hamburg.ccc.de, this would need an entry in the hamburg.ccc.de zone like this:

   mywebservice IN CNAME public-reverse-proxy
   

3. Next add the VM to the relevant inventory groups. For a web service running on docker compose, the following groups would be needed:
   • docker_compose_hosts
   • nginx_hosts
   • certbot_hosts.
4. Then configuration for the VM hosting the web service needs to be provided, which should look something like this:

# inventories/chaosknoten/host_vars/myservice.yaml
certbot__acme_account_email_address: le-admin@hamburg.ccc.de
certbot__certificate_domains:
  - "mywebservice.hamburg.ccc.de"
certbot__new_cert_commands:
  - "systemctl reload nginx.service"

docker_compose__compose_file_content: "{{ lookup('ansible.builtin.template', 'resources/chaosknoten/myservice/docker_compose/compose.yaml.j2') }}"

nginx__version_spec: ""
nginx__configurations:
  - name: mywebservice.hamburg.ccc.de
    content: "{{ lookup('ansible.builtin.file', 'resources/chaosknoten/myservice/nginx/mywebservice.hamburg.ccc.de.conf') }}"

This would create a compose.yaml on the host from the template resources/chaosknoten/example/docker_compose/compose.yaml.j2' and an nginx configuration from resources/chaosknoten/myservice/nginx/mywebservice.hamburg.ccc.de.conf, so both files need to be filled accordingly. Of course, depending on your service, you might need additional or different configuration.
Generally you should look at the configuration of existing hosts and the provided roles for guidance. 5. Finally configure the web service on the new host by running the Ansible playbook for it:

ansible-playbook playbooks/deploy.yaml -i inventories/chaosknoten/hosts.yaml -l myservice 

Additional Resources

• For storing secrets using SOPS, see: SOPS: Storing Secrets
• After setting up the web service, you should also take care of setting up monitoring it, see: Monitoring: Gatus