---
title: Web Service
summary: How to Setup a Web Service
---

# Web Service

This guide assumes you followed [New Chaosknoten VM](./new-chaosknoten-vm.md) 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](https://git.hamburg.ccc.de/CCCHH/ansible-infra/src/branch/main/resources/chaosknoten/auth-dns/zones/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:
  ```yaml
  # 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](./sops-storing-secrets.md)
- After setting up the web service, you should also take care of setting up monitoring it, see: [Monitoring: Gatus](./monitoring-gatus.md)