242 lines
7.8 KiB
Markdown
242 lines
7.8 KiB
Markdown
# 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.
|
|
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
|
|
```
|
|
|
|
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
|
|
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. 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.
|