# Drivers Hub: Frontend Docker Deployment

```text
    ____       _                         __  __      __
   / __ \_____(_)   _____  __________   / / / /_  __/ /_
  / / / / ___/ / | / / _ \/ ___/ ___/  / /_/ / / / / __ \
 / /_/ / /  / /| |/ /  __/ /  (__  )  / __  / /_/ / /_/ /
/_____/_/  /_/ |___/\___/_/  /____/  /_/ /_/\__,_/_.___/
```

Docker deployment for [Drivers Hub: Frontend](https://github.com/CharlesWithC/HubFrontend).
The container serves the static frontend with Nginx.

## Tested upstream revision

This deployment is tested with upstream `main` at commit
[`7bf7cfb`](https://github.com/CharlesWithC/HubFrontend/commit/7bf7cfba5474f8699aa475a3e19b5ab4ec2d38fb),
which declares package version `3.6.0`. The latest release tag, `v3.4.4`, points
to an older revision and is not the tested source revision.

## Configure the deployment

Get the frontend source code. Then, create the deployment configuration:

```bash
git clone https://github.com/CharlesWithC/HubFrontend.git upstream/HubFrontend
cp .env.example .env
```

Set `VITE_CONFIG_URL` to the client configuration endpoint of your Drivers Hub
backend. The URL usually has this format:

```text
https://hub.example.com/api/client/config/global
```

Create an hCaptcha site for the public frontend domain. Set its public site key
as `VITE_HCAPTCHA_SITEKEY`. Set the related secret in the backend
`config/config.json` file. The site key is included in the frontend files and is
not a secret.

Enable the `client-config` external plugin in the backend configuration. The
backend `abbr` value must match the API prefix without its leading slash. For
example, use `"abbr": "api"` with `"prefix": "/api"`.

The frontend uses the Vite values during the image build. Rebuild the image after
you change `.env`, including the hCaptcha site key.

The build removes the hard-coded upstream Google Analytics integration and its
consent dialog. If upstream removes the known integration, the build skips this
step. If an unknown Analytics implementation remains, the build stops instead
of publishing it.

The build also replaces the hard-coded external login avatar with the bundled
`/logo.png` file. If upstream removes the known avatar URL, the build skips this
step.

The runtime image does not include the upstream Electron entry points and
configuration. These files are not used by the web deployment.

## Start the deployment

```bash
docker compose build
docker compose up -d
docker compose ps
```

By default, the frontend is available at `http://127.0.0.1:18080`. The default
bind address is suitable for a reverse proxy on the Docker host.

## Configure a reverse proxy

The following examples assume that the reverse proxy runs on the Docker host.
Replace `hub.example.com` with the public frontend domain. Keep
`FRONTEND_BIND=127.0.0.1:18080` in the frontend `.env`. The examples also assume
that Drivers Hub: Backend listens on `127.0.0.1:17777` and uses the `/api` prefix.
They do not publish the API documentation or the upstream service restart
endpoint. The restart endpoint does not manage a Docker container. All other
API routes remain available to the frontend and configured external services.

### Standalone Nginx

Create an Nginx virtual host:

```nginx
server {
    listen 80;
    listen [::]:80;
    server_name hub.example.com;

    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name hub.example.com;

    ssl_certificate /etc/letsencrypt/live/hub.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/hub.example.com/privkey.pem;

    # Do not publish API schemas or interactive API documentation.
    # The upstream restart endpoint cannot restart this Docker container.
    location ~ ^/api/(?:docs?(?:/|$)|redoc/?$|openapi\.json$|restart$) {
        return 404;
    }

    location /api/ {
        proxy_pass http://127.0.0.1:17777;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location / {
        proxy_pass http://127.0.0.1:18080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

Set the certificate paths for your system. Test and reload Nginx:

```bash
sudo nginx -t
sudo systemctl reload nginx
```

See the [Nginx proxy module documentation](https://nginx.org/en/docs/http/ngx_http_proxy_module.html)
for more information.

### Standalone Caddy

Add this site block to the Caddyfile:

```caddyfile
hub.example.com {
    # Do not publish API schemas or interactive API documentation.
    # The upstream restart endpoint cannot restart this Docker container.
    @blocked path /api/openapi.json /api/doc /api/doc/* /api/docs /api/docs/* /api/redoc /api/restart
    handle @blocked {
        respond 404
    }

    handle /api/* {
        reverse_proxy 127.0.0.1:17777
    }

    handle {
        reverse_proxy 127.0.0.1:18080
    }
}
```

Caddy obtains and renews the TLS certificate when the domain points to the
server and ports 80 and 443 are available. Validate and reload Caddy:

```bash
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
```

See the [Caddy reverse proxy documentation](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy)
for more information.

### Plesk Nginx drop-in

Use a domain or subdomain that has a valid TLS certificate in Plesk.

1. Open **Domains > hub.example.com > Dashboard > PHP**.
2. Disable **PHP Support** and apply the change.
3. Open **Hosting & DNS > Apache & nginx Settings**.
4. Disable **Proxy mode** and apply the change.
5. Add this block to **Additional nginx directives**:

```nginx
# Do not publish API schemas or interactive API documentation.
# The upstream restart endpoint cannot restart this Docker container.
location ~ ^/api/(?:docs?(?:/|$)|redoc/?$|openapi\.json$|restart$) {
    return 404;
}

location /api/ {
    proxy_pass http://127.0.0.1:17777;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

location / {
    proxy_pass http://127.0.0.1:18080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}
```

Apply the configuration. Do not add a `server` block in this field. Plesk
creates the `server` block and manages TLS. Proxy mode must be disabled before
you add `location /`. Otherwise, Plesk creates a duplicate location.

See the [Plesk reverse proxy instructions](https://support.plesk.com/hc/en-us/articles/12388464421143-How-to-pass-requests-from-a-Plesk-hosted-domain-to-the-application-listening-on-a-local-port)
for more information.

## Update the frontend

Update the frontend source code. Then, rebuild the container:

```bash
git -C upstream/HubFrontend pull --ff-only
docker compose build
docker compose up -d
```

## Operate the deployment

```bash
# Show the frontend logs.
docker compose logs -f frontend

# Rebuild the image after a configuration change.
docker compose build frontend
docker compose up -d frontend
```

## Authors and license

This Docker deployment is developed by Kosmos <me@kosmos.ac> and is licensed
under the GNU Affero General Public License v3.0. See [LICENSE](LICENSE).

[Drivers Hub: Frontend](https://github.com/CharlesWithC/HubFrontend) is developed
by [CharlesWithC](https://charlws.com) and is licensed under the GNU Affero
General Public License v3.0. Drivers Hub remains a separate upstream project.