Jump to content

Services:Step By Step: Difference between revisions

From jb-vpn.uk Wiki
← Older edit
Major update - troubleshooting guide: Step-by-Step Process for Adding Services (18 sections)
Updated documentation from markdown files
 
Line 1: Line 1:
Follow these steps to add a new service to the reverse proxy system.
Follow these steps to expose a new service through the VPS reverse proxy (Caddy).


== Step 1: Create Nginx Configuration File ==
== Step 1: Add a Caddy site block ==


Create a new configuration file in <code>/etc/nginx/sites-available/</code>:
Edit <code>/etc/caddy/Caddyfile</code> and add a block for your hostname.


<pre class="lang-bash">
'''VPS-local service''' (Docker on <code>127.0.0.1</code>):
sudo nano /etc/nginx/sites-available/newservice.jb-vpn.uk
</pre>
 
'''Basic HTTP Configuration Template''':
 
<pre class="lang-nginx">
server {
    server_name newservice.jb-vpn.uk;
 
    location / {
=== Reverse Proxy to Synology's internal VPN IP and service port ===
        proxy_pass http://10.8.0.2:PORT_NUMBER;
        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;
=== Necessary for Synology Reverse Proxy compatibility ===
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
=== Timeouts for long-running requests ===
        proxy_read_timeout 300s;
        proxy_connect_timeout 75s;
    }
 
    listen 80;


<pre>
newservice.jb-vpn.uk {
reverse_proxy http://127.0.0.1:PORT {
header_up Host {host}
header_up X-Real-IP {remote}
header_up X-Forwarded-For {remote}
header_up X-Forwarded-Proto {scheme}
}
}
}
</pre>
</pre>


'''Replace''':
'''NAS service''' (via OpenVPN at <code>10.8.0.2</code>):
* <code>newservice.jb-vpn.uk</code> with your subdomain


* <code>PORT_NUMBER</code> with your service's port
<pre>
 
newservice.jb-vpn.uk {
'''For HTTPS Internal Services''':
reverse_proxy http://10.8.0.2:PORT {
 
header_up Host {host}
If your internal service uses HTTPS, change the proxy_pass line:
header_up X-Real-IP {remote}
<pre class="lang-nginx">
header_up X-Forwarded-For {remote}
proxy_pass https://10.8.0.2:PORT_NUMBER;
header_up X-Forwarded-Proto {scheme}
</pre>
}
 
}
'''For Services Requiring Special Headers''':
 
Some services (like Plex) require additional headers. See [Service Examples](service-examples.md) for reference.
 
== Step 2: Enable the Site ==
 
Create a symlink to enable the site:
 
<pre class="lang-bash">
sudo ln -s /etc/nginx/sites-available/newservice.jb-vpn.uk /etc/nginx/sites-enabled/newservice.jb-vpn.uk
</pre>
</pre>


== Step 3: Test Nginx Configuration ==
'''NAS HTTPS backend''' (e.g. DSM-style):


Always test the configuration before reloading:
<pre class="lang-bash">
sudo nginx -t
</pre>
'''Expected Output''':
<pre>
<pre>
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
newservice.jb-vpn.uk {
nginx: configuration file /etc/nginx/nginx.conf test is successful
reverse_proxy https://10.8.0.2:PORT {
transport http {
tls_insecure_skip_verify
}
header_up Host {host}
header_up X-Forwarded-Proto {scheme}
}
}
</pre>
</pre>


'''If there are errors''': Fix them before proceeding. Common issues:
Replace <code>PORT</code> with the internal port and ensure DNS points to the VPS.
* Syntax errors (missing semicolons, brackets)
 
* Duplicate server names
 
* Invalid port numbers
 
== Step 4: Reload Nginx ==


Reload nginx to apply the new configuration (graceful reload, no downtime):
== Step 2: Validate and reload ==


<pre class="lang-bash">
<pre class="lang-bash">
sudo systemctl reload nginx
caddy validate --config /etc/caddy/Caddyfile
systemctl reload caddy
</pre>
</pre>


== Step 5: Verify HTTP Access ==
== Step 3: Verify connectivity ==
 
Test that the service is accessible via HTTP:


<pre class="lang-bash">
<pre class="lang-bash">
curl -I http://newservice.jb-vpn.uk
nslookup newservice.jb-vpn.uk
curl -I https://newservice.jb-vpn.uk
</pre>
</pre>


You should receive an HTTP response. If you get a connection error:
For NAS backends, confirm VPN first:
* Check DNS: <code>nslookup newservice.jb-vpn.uk</code>
 
* Verify service is running: <code>curl http://10.8.0.2:PORT_NUMBER</code>
 
* Check nginx logs: <code>tail -f /var/log/nginx/error.log</code>
 
== Step 6: Set Up SSL Certificate ==
 
Use Certbot to automatically configure SSL:


<pre class="lang-bash">
<pre class="lang-bash">
sudo certbot --nginx -d newservice.jb-vpn.uk --non-interactive --agree-tos --redirect --email admin@jb-vpn.uk
ping -c 2 10.8.0.2
curl -sI -m 5 http://10.8.0.2:PORT | head -1
</pre>
</pre>


'''What this does''':
== Step 4: TLS ==
* Requests SSL certificate from Let's Encrypt


* Configures nginx for HTTPS
Caddy obtains and renews Let's Encrypt certificates automatically when:


* Sets up HTTP to HTTPS redirect
* DNS for the hostname points to <code>87.106.61.62</code>


* Configures automatic renewal
* Ports 80 and 443 are reachable on the VPS


'''If Certbot fails''':
Check logs if HTTPS fails on first request:
* Verify DNS is pointing to VPS: <code>nslookup newservice.jb-vpn.uk</code>
 
* Ensure port 80 is open and accessible
 
* Check firewall rules: <code>sudo iptables -L -n -v</code>
 
== Step 7: Verify HTTPS Access ==
 
Test that HTTPS is working:


<pre class="lang-bash">
<pre class="lang-bash">
curl -I https://newservice.jb-vpn.uk
journalctl -u caddy -n 50
</pre>
 
You should receive a 200 OK or similar response with SSL certificate details.
 
== Step 8: Test in Browser ==
 
Open your browser and navigate to:
<pre>
https://newservice.jb-vpn.uk
</pre>
</pre>


Verify:
== Step 5: Browser test ==
* SSL certificate is valid (green lock icon)


* Service loads correctly
Open <code>https://newservice.jb-vpn.uk</code> and confirm the service loads with a valid certificate.


* All functionality works as expected
== Removing a service ==


== Removing a Service ==
# Remove the site block from <code>/etc/caddy/Caddyfile</code>
# <code>caddy validate --config /etc/caddy/Caddyfile</code>
# <code>systemctl reload caddy</code>


To remove a service:
== Related documentation ==
 
=== '''Disable the site''': ===
  <pre class="lang-bash">
  sudo rm /etc/nginx/sites-enabled/service.jb-vpn.uk
</pre>
 
== '''Test configuration''': ==
  <pre class="lang-bash">
  sudo nginx -t
</pre>
 
== '''Reload nginx''': ==
  <pre class="lang-bash">
  sudo systemctl reload nginx
</pre>
 
== '''Optional - Remove configuration file''': ==
  <pre class="lang-bash">
  sudo rm /etc/nginx/sites-available/service.jb-vpn.uk
</pre>
 
== '''Optional - Revoke SSL certificate''': ==
  <pre class="lang-bash">
  sudo certbot revoke --cert-path /etc/letsencrypt/live/service.jb-vpn.uk/cert.pem
  sudo certbot delete --cert-name service.jb-vpn.uk
</pre>


== Related Documentation ==
* [Prerequisites Prerequisites]


* [[Documentation:Prerequisites](Prerequisites|- Requirements before starting
* [Service Examples Service Examples]


* [Configuration Options]])(configuration-options.md) - Advanced configuration
* [Configuration Options Configuration Options]


* [Service Examples](service-examples.md) - Service-specific examples
* [[Services:Current Services]]


* [[Documentation:Index|Troubleshooting]] - Common issues


[[Category:Documentation]]
[[Category:Documentation]]
[[Category:Documentation/Services]]
[[Category:Documentation/Services]]
[[Category:Documentation/Services/Adding Services]]
[[Category:Documentation/Services/Adding Services]]

Latest revision as of 14:04, 16 May 2026

Follow these steps to expose a new service through the VPS reverse proxy (Caddy).

Step 1: Add a Caddy site block

[edit]

Edit /etc/caddy/Caddyfile and add a block for your hostname.

VPS-local service (Docker on 127.0.0.1): 

newservice.jb-vpn.uk {
	reverse_proxy http://127.0.0.1:PORT {
		header_up Host {host}
		header_up X-Real-IP {remote}
		header_up X-Forwarded-For {remote}
		header_up X-Forwarded-Proto {scheme}
	}
}

NAS service (via OpenVPN at 10.8.0.2): 

newservice.jb-vpn.uk {
	reverse_proxy http://10.8.0.2:PORT {
		header_up Host {host}
		header_up X-Real-IP {remote}
		header_up X-Forwarded-For {remote}
		header_up X-Forwarded-Proto {scheme}
	}
}

NAS HTTPS backend (e.g. DSM-style): 

newservice.jb-vpn.uk {
	reverse_proxy https://10.8.0.2:PORT {
		transport http {
			tls_insecure_skip_verify
		}
		header_up Host {host}
		header_up X-Forwarded-Proto {scheme}
	}
}

Replace PORT with the internal port and ensure DNS points to the VPS.

Step 2: Validate and reload

[edit]
caddy validate --config /etc/caddy/Caddyfile
systemctl reload caddy

Step 3: Verify connectivity

[edit]
nslookup newservice.jb-vpn.uk
curl -I https://newservice.jb-vpn.uk

For NAS backends, confirm VPN first: 

ping -c 2 10.8.0.2
curl -sI -m 5 http://10.8.0.2:PORT | head -1

Step 4: TLS

[edit]

Caddy obtains and renews Let's Encrypt certificates automatically when:

  • DNS for the hostname points to 87.106.61.62
  • Ports 80 and 443 are reachable on the VPS

Check logs if HTTPS fails on first request: 

journalctl -u caddy -n 50

Step 5: Browser test

[edit]

Open https://newservice.jb-vpn.uk and confirm the service loads with a valid certificate.

Removing a service

[edit]
  1. Remove the site block from /etc/caddy/Caddyfile
  2. caddy validate --config /etc/caddy/Caddyfile
  3. systemctl reload caddy
[edit]
  • [Prerequisites Prerequisites]
  • [Service Examples Service Examples]
  • [Configuration Options Configuration Options]
Retrieved from "https://wiki.jb-vpn.uk/index.php?title=Services:Step_By_Step&oldid=256"