HubFrontendDocker/README.md

# 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.

## 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.

## 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.

### 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;

    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 $remote_addr;
        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 $remote_addr;
        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 {
    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
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 $remote_addr;
    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 $remote_addr;
    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.