From 10007d613a36cf2c89ae0f24fc08ad496bfa52a6 Mon Sep 17 00:00:00 2001 From: Zev Roblox Doors 2 Obby Creator Owner <116480526+ZevRobloxDoors2@users.noreply.github.com> Date: Thu, 29 Jan 2026 14:23:03 +0000 Subject: [PATCH] site(docs): publish docs/ via GitHub Pages + add Docker/nginx self-hosting, systemd template and deploy scripts --- .env.sample | 2 ++ .github/workflows/publish-docs.yml | 30 +++++++++++++++++++++++++++ README.md | 26 +++++++++++++++++++++++ deploy/nebulo-site.service | 22 ++++++++++++++++++++ deploy/nginx.conf | 33 ++++++++++++++++++++++++++++++ deploy/start.sh | 30 +++++++++++++++++++++++++++ docker-compose.yml | 22 ++++++++++++++++++++ docs/_sidebar.md | 5 +++++ docs/index.html | 27 ++++++++++++++++++++++++ 9 files changed, 197 insertions(+) create mode 100644 .env.sample create mode 100644 .github/workflows/publish-docs.yml create mode 100644 deploy/nebulo-site.service create mode 100644 deploy/nginx.conf create mode 100644 deploy/start.sh create mode 100644 docker-compose.yml create mode 100644 docs/_sidebar.md create mode 100644 docs/index.html diff --git a/.env.sample b/.env.sample new file mode 100644 index 00000000..7ef37255 --- /dev/null +++ b/.env.sample @@ -0,0 +1,2 @@ +# Port the site will be exposed on the host (requires firewall/DNS configured) +PORT=80 diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml new file mode 100644 index 00000000..d7fea687 --- /dev/null +++ b/.github/workflows/publish-docs.yml @@ -0,0 +1,30 @@ +name: Publish docs to GitHub Pages + +on: + push: + branches: [ master ] + workflow_dispatch: {} + +jobs: + publish: + name: Publish `docs/` ➜ GitHub Pages + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Configure Pages + uses: actions/configure-pages@v3 + + - name: Upload docs/ + uses: actions/upload-pages-artifact@v1 + with: + path: docs + + - name: Deploy to GitHub Pages + uses: actions/deploy-pages@v1 + + - name: Post-deploy info + run: | + echo "Published docs/ to GitHub Pages. URL will be available in the Pages section of the repo settings." diff --git a/README.md b/README.md index 57ba4972..26a7108e 100755 --- a/README.md +++ b/README.md @@ -60,6 +60,32 @@ Nebulo is wholly an original piece of software: It doesn't use any other depende # FAQ For a growing collection of frequenty asked questions, [take a look here](FAQ.md). +## Website — public docs & self-hosting +You can make the repository documentation publicly reachable in two ways (both are configured in this repo): + +1) **GitHub Pages (always-on, recommended)** — the repo is configured to publish the `docs/` folder automatically. The workflow runs on push to `master` and publishes to GitHub Pages. + + Quick: Push your changes and the site will appear in the repository *Pages* settings (or at `https://.github.io/Nebulo`). + +2) **Self-host (Docker + nginx)** — use the provided `docker-compose.yml` to run a persistent site on any server. + + - Start: + ```bash + cp .env.sample .env # edit PORT if needed + ./deploy/start.sh # starts container and waits for healthcheck + ``` + - Systemd (example): copy `deploy/nebulo-site.service` to `/etc/systemd/system/`, then `systemctl daemon-reload && systemctl enable --now nebulo-site`. + +Notes and TLS: +- GitHub Pages gives HTTPS by default — no extra work required. +- For self-hosting: point your domain A record to the host, open the port in your firewall, and obtain a cert (Certbot or reverse-proxy). The nginx config includes `/.well-known/acme-challenge/` for ACME. +- The Docker Compose service is configured with `restart: unless-stopped` so it will automatically come back after reboots. + +Security & availability checklist: +- Open only the required ports (80/443) and use HTTPS in production. +- Add a DNS A record for your domain and enable a firewall rule for the chosen port. +- Monitor uptime (systemd + `Restart=` policy + Docker healthcheck are included). + # Help wanted Translations are important to reach as broad of an audience as possible and for non-english speakers to be able to use the app to its full extent. [Head over to the translation guide](TRANSLATING.md) to see how you can help! diff --git a/deploy/nebulo-site.service b/deploy/nebulo-site.service new file mode 100644 index 00000000..4f7a6c5f --- /dev/null +++ b/deploy/nebulo-site.service @@ -0,0 +1,22 @@ +[Unit] +Description=Nebulo static site (docker-compose) +After=network.target docker.service +Requires=docker.service + +[Service] +Type=oneshot +WorkingDirectory=/workspaces/Nebulo +EnvironmentFile=/workspaces/Nebulo/.env +ExecStart=/usr/bin/docker compose up -d nebulo-site +ExecStop=/usr/bin/docker compose down +RemainAfterExit=yes +TimeoutStartSec=120 +Restart=on-failure + +[Install] +WantedBy=multi-user.target + +# Usage: +# 1) copy this file to /etc/systemd/system/nebulo-site.service +# 2) edit WorkingDirectory if you moved the repo +# 3) systemctl daemon-reload && systemctl enable --now nebulo-site.service diff --git a/deploy/nginx.conf b/deploy/nginx.conf new file mode 100644 index 00000000..d63caa96 --- /dev/null +++ b/deploy/nginx.conf @@ -0,0 +1,33 @@ +server { + listen 80 default_server; + listen [::]:80 default_server; + server_name _; + + root /usr/share/nginx/html; + index index.html index.htm; + + # Serve docsify (client-side) + static assets + location / { + try_files $uri $uri/ /index.html =404; + } + + # Let's Encrypt ACME challenge + location ^~ /.well-known/acme-challenge/ { + default_type "text/plain"; + root /usr/share/nginx/html; + } + + # Security headers (no HSTS here because TLS must be enabled before using it) + add_header X-Frame-Options "SAMEORIGIN" always; + add_header X-Content-Type-Options "nosniff" always; + add_header Referrer-Policy "no-referrer-when-downgrade" always; + add_header X-XSS-Protection "1; mode=block" always; + + # Caching for assets + location ~* \.(?:css|js|svg|png|jpg|jpeg|gif|ico)$ { + expires 7d; + add_header Cache-Control "public, must-revalidate"; + } + + error_page 404 /404.html; +} diff --git a/deploy/start.sh b/deploy/start.sh new file mode 100644 index 00000000..fec500a5 --- /dev/null +++ b/deploy/start.sh @@ -0,0 +1,30 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Start the Nebulo docs site (docker-compose) +# Usage: ./deploy/start.sh + +ROOT="$(cd "$(dirname "$0")/.." && pwd)" +cd "$ROOT" + +# create .env from sample if missing +if [ ! -f .env ] && [ -f .env.sample ]; then + cp .env.sample .env + echo "Created .env from .env.sample — edit .env to change PORT" +fi + +docker compose pull nebulo-site || true +docker compose up -d --remove-orphans + +echo "Waiting for healthcheck (30s)..." +sleep 3 +for i in {1..10}; do + if docker inspect --format='{{json .State.Health.Status}}' nebulo-site 2>/dev/null | grep -q healthy; then + echo "nebulo-site is healthy and serving docs/" + exit 0 + fi + sleep 3 +done + +echo "If the container is not healthy, check logs: docker logs nebulo-site" >&2 +exit 1 diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 00000000..c361db1c --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,22 @@ +version: '3.8' + +services: + nebulo-site: + image: nginx:stable-alpine + container_name: nebulo-site + ports: + - "${PORT:-80}:80" + volumes: + - ./docs:/usr/share/nginx/html:ro + - ./deploy/nginx.conf:/etc/nginx/conf.d/default.conf:ro + restart: unless-stopped + healthcheck: + test: ["CMD-SHELL","wget -qS --spider http://127.0.0.1:${PORT:-80} || exit 1"] + interval: 30s + timeout: 5s + retries: 3 + logging: + driver: "json-file" + options: + max-size: "5m" + max-file: "3" diff --git a/docs/_sidebar.md b/docs/_sidebar.md new file mode 100644 index 00000000..5c929f76 --- /dev/null +++ b/docs/_sidebar.md @@ -0,0 +1,5 @@ +* [Home](DNSRULE_WILDCARDS.md) +* [DNS wildcards](DNSRULE_WILDCARDS.md) +* [DNS-over-QUIC (DOQ)](DOQ.md) +* [Non-VPN mode](NONVPNMODE.md) +* [Full project on GitHub](https://github.com/Ch4t4r/Nebulo) diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 00000000..754f9b35 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,27 @@ + + + + + + Nebulo — Documentation + + + + + + +
Loading…
+ + + + + +