HubFrontendDocker/README.md

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 instead. It provides the backend, frontend, database, and Valkey as one deployment. Existing installations can use the migration instructions.

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

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

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.

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:

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:

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

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:

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.