# Drivers Hub: Frontend Docker Deployment

## Deprecated

This repository is no longer maintained and does not contain the latest
deployment fixes. Do not use it for a new installation. Use
[DriversHubDockerAIO](https://github.com/kosmosac/DriversHubDockerAIO) instead.
It provides the backend, frontend, database, and Valkey as one deployment.
Existing installations can use the
[migration instructions](https://github.com/kosmosac/DriversHubDockerAIO#migrate-from-the-separate-deployment-repositories).

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

Docker deployment for [Drivers Hub: Frontend](https://github.com/CharlesWithC/HubFrontend).
The container serves the static frontend with Nginx.
Use it with the
[Drivers Hub: Backend Docker Deployment](https://gitea.kosmos.ac/kosmos/HubBackendDocker).

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

The clone command below gets the current upstream default branch. A newer
upstream revision can be incompatible with this deployment. If a build or
runtime error occurs after an upstream update, compare the checked-out revision
with the tested revision above.

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

The provided `.env.example` already uses the standard backend prefix and client
configuration path. In `VITE_CONFIG_URL`, replace `hub.example.com` with your
public Hub domain:

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

Create an hCaptcha site for the public frontend domain. Set its public site key
in the provided `VITE_HCAPTCHA_SITEKEY` setting. The backend deployment README
shows the related `captcha.secret` setting. The site key is included in the
frontend files and is not a secret.

The documented backend configuration already enables the required
`client-config` external plugin. The single-hub build derives the API base URL
from `VITE_CONFIG_URL`. The backend `abbr` can contain the VTC abbreviation and
does not have to match the API prefix. This deployment-specific behavior does
not apply when `VITE_USE_MULTIHUB` is `true`.

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

The web image does not load the Google Analytics integration from the upstream
frontend. It uses the bundled `/logo.png` file for the login avatar and does not
include Electron entry points or Electron configuration.

## 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. The examples use the
default addresses from both deployment repositories:
`FRONTEND_BIND=127.0.0.1:18080` for the frontend and
`BACKEND_BIND=127.0.0.1:17777` with the `/api` prefix for the backend. You do not
have to change these values. If you do change one, update the related proxy
target below. The examples 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.