Files

cpu 4cae455892 PWA fixed

added systemd service howto

traefik

nginix set_real_ip_from

improved readme

visuals fixed on mobile

labels removed

updated readme

fixed visuals

overlay for the hotkey

disable screen lock

clean up

git precommit hooks

clean up

clean up

update

check for update feature

added build-time information

fixed date

clean up

added hook script

fix

fix

fix

hooks fixed

webhook setup

players stay in run all timers mode

mqtt

mqtt allways connected

mqtt messages work

capturing mqtt in edit player

mqtt in Setup

updated readme

state of the mqtt

Global Pass turn

offline mode

docs: update documentation to reflect current codebase and MQTT features

- Update README.md with global MQTT commands
- Enhance architecture.md with comprehensive data model and MQTT state
- Update development.md with project structure and workflow
- Remove redundant script listings
- Fix formatting and organization

2025-05-19 21:43:00 +02:00

7.4 KiB

Raw Blame History

Deployment Guide: Nexus Timer

This guide outlines the steps to deploy and manage the Nexus Timer application on a server using Docker, Traefik (as a reverse proxy), and systemd, with an optional automated deployment via Gitea webhooks.

Initial Server Setup
Exposing the App Behind Traefik
Automating Updates with Webhooks (Gitea)
Manual Updates (Fallback)
Troubleshooting & Logs

Initial Server Setup

On the Server

Navigate to your preferred service directory on the server (e.g., /virt).

cd /virt

Clone the repository (only the latest commit for faster cloning).

git clone --depth 1 https://gitea.virtonline.eu/2HoursProject/nexus-timer.git
cd nexus-timer

If you will run the container on the Docker network traefik (or any other pre-existing network), find its IP subnet to allow Nginx inside the container to correctly identify the real client IP.

docker network inspect traefik --format '{{(index .IPAM.Config 0).Subnet}}'

You'll get an output like 172.22.0.0/16.

Set this subnet in the nginx.conf file within your cloned repository before building the image. For example:

set_real_ip_from 172.22.0.0/16;

Build the Docker image for the application.

docker build -t virt-nexus-timer .

Exposing the App Behind Traefik (Reverse Proxy)

This setup assumes you have Traefik running and configured to watch for Docker labels.

Review the provided docker labels and systemd service file

The docker/traefik.labels file contains Docker labels that Traefik uses for routing and HTTPS. Review and adjust them if necessary. Copy the example label file to its destination (one level up, to be read by systemd).

cp docker/traefik.labels labels

View the example systemd service definition to understand how the Docker container will be managed.

cat systemd/virt-nexus-timer.service

Create the systemd service

Use systemctl edit to create or overwrite the service file. This is the recommended way to manage custom systemd units.

sudo systemctl edit --force --full virt-nexus-timer.service

The editor will open. Paste the content from your systemd/virt-nexus-timer.service file into the editor, then save and exit (e.g., Ctrl+X, then Y, then Enter in nano).

Enable the service to start on system boot and start it immediately.

sudo systemctl enable --now virt-nexus-timer.service

Check the service status to ensure it's running correctly.

systemctl status virt-nexus-timer.service

Look for "active (running)".

Test the web application

Verify that the application is accessible via HTTPS through Traefik:

curl https://nexus-timer.virtonline.eu

Or open it in your browser: https://nexus-timer.virtonline.eu

Automating Updates with Webhooks (Gitea)

Instead of manually pulling, building, and restarting on the server, you can automate this process using a webhook. Gitea will notify a webhook service running on your server, which will then execute a deployment script.

Install the webhook service

sudo install webhook

Allow your Gitea instance to reach the webhook service on your server (e.g., 10.0.0.1:9000). Ensure Gitea's ALLOWED_HOST_LIST in its app.ini includes this IP.

The Redeployment Script

The webhook service will execute the script hooks/redeploy.sh. If webhook runs as a non-root user (recommended), that user will need passwordless sudo permission to restart the virt-nexus-timer.service. You can grant this by editing the sudoers file:

sudo visudo

and adding a line like:

webhooksvc ALL=(ALL) NOPASSWD: /usr/bin/systemctl restart virt-nexus-timer.service

Replace webhooksvc with the actual user webhook runs as. If webhook runs as root, this is not necessary but less secure overall.

Configure the `webhook` Service

Create or edit the main webhook configuration file, typically at /etc/webhook.conf. Add the JSON object from hooks/webhook.conf to the array in the file (or create the file if it's new).
Note: Replace YOUR_VERY_STRONG_SECRET_TOKEN_HERE_REPLACE_ME with a strong, unique secret.

Set Up webhook as a Systemd Service

Use systemctl edit to create or overwrite the service file. This is the recommended way to manage custom systemd units.

sudo systemctl edit --force --full webhook.service

The editor will open. Paste the content from your systemd/webhook.service file into the editor, then save and exit (e.g., Ctrl+X, then Y, then Enter in nano).

Enable, and start the webhook service:

sudo systemctl enable --now webhook.service
sudo systemctl status webhook.service

Configure Webhook in Gitea

Navigate to your Gitea repository: https://gitea.virtonline.eu/2HoursProject/nexus-timer
Go to Settings -> Webhooks.
Click Add Webhook and choose Gitea.
Target URL: http://10.0.0.1:9000/hooks/redeploy-nexus-timer
(The redeploy-nexus-timer part must match the id in your /etc/webhook.conf)
HTTP Method: POST
POST Content Type: application/json
Secret: Enter the exact same strong secret token you used in /etc/webhook.conf (e.g., YOUR_VERY_STRONG_SECRET_TOKEN_HERE_REPLACE_ME).
Trigger On: Select Push Events. You can further refine this to specific branches if your webhook.conf doesn't already filter by branch (though redundant filtering is fine).
Ensure Enable this webhook is checked.
Click Add Webhook.

Test the Webhook

In Gitea, on the Webhooks settings page for the webhook you just created, click Test Delivery.
Check the Gitea UI for the response. It should show a 200 OK and include the output from your redeploy.sh script.
Push a small change to your main (or configured) branch to trigger a real deployment.

Firewall Considerations

If your server has a firewall (e.g., ufw), ensure that port 9000 (or whichever port you configured for webhook) is allowed for incoming connections from your Gitea server's IP address or network.

Example for ufw allowing any connection to 10.0.0.1:9000 (restrict source IP if possible):

sudo ufw allow to 10.0.0.1 port 9000 proto tcp comment 'Gitea Webhook'

If Gitea is external, use its specific source IP instead of 'any' for better security.

sudo ufw allow from <GITEA_SERVER_IP> to 10.0.0.1 port 9000 proto tcp comment 'Gitea Webhook'

Reload ufw if changes are made:

sudo ufw reload

Manual Updates (Fallback)

Navigate to the application directory on your server.

cd /virt/nexus-timer

Pull the latest changes from the repository, rebuild the Docker image, and restart the systemd service.

git pull && docker build -t virt-nexus-timer . && sudo systemctl restart virt-nexus-timer.service

The previously installed Progressive Web App (PWA) should update automatically upon next launch or offer an upgrade prompt.

Troubleshooting & Logs

View real-time logs for the application service:

journalctl -fu virt-nexus-timer.service

View real-time logs for the webhook service:

journalctl -fu webhook.service

Check the custom log file for the redeployment script (if configured):

tail -f /var/log/webhook-redeploy-nexus-timer.log

Check Gitea's webhook delivery logs for request/response details and errors.

7.4 KiB Raw Blame History