HubFrontendDocker/README.md

Drivers Hub: Frontend Docker Deployment

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

Docker deployment for Drivers Hub: Frontend. The container serves the static frontend with Nginx.

Tested upstream revision

This deployment is tested with upstream main at commit 7bf7cfb, 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:

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:

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

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:

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:

sudo nginx -t
sudo systemctl reload nginx

See the Nginx proxy module documentation for more information.

Standalone Caddy

Add this site block to the 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:

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

See the Caddy reverse proxy documentation 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:

# 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 for more information.

Update the frontend

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

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

Operate the deployment

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

Drivers Hub: Frontend is developed by CharlesWithC and is licensed under the GNU Affero General Public License v3.0. Drivers Hub remains a separate upstream project.