Jump to content

Services:Step By Step: Difference between revisions

From jb-vpn.uk Wiki
Added troubleshooting guide: Step-by-Step Process for Adding Services
 
Updated documentation from markdown files
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
= Step-by-Step Process for Adding Services =
Follow these steps to expose a new service through the VPS reverse proxy (Caddy).


Follow these steps to add a new service to the reverse proxy system.
== Step 1: Add a Caddy site block ==


== Step 1: Create Nginx Configuration File ==
Edit <code>/etc/caddy/Caddyfile</code> and add a block for your hostname.


Create a new configuration file in <code>/etc/nginx/sites-available/</code>:
'''VPS-local service''' (Docker on <code>127.0.0.1</code>):


<pre class="lang-bash">
<pre>
sudo nano /etc/nginx/sites-available/newservice.jb-vpn.uk
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>


'''Basic HTTP Configuration Template''':
'''NAS service''' (via OpenVPN at <code>10.8.0.2</code>):
 
<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://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}
}
}
}
</pre>
</pre>


'''Replace''':
'''NAS HTTPS backend''' (e.g. DSM-style):
'' <code>newservice.jb-vpn.uk</code> with your subdomain
'' <code>PORT_NUMBER</code> with your service's port


'''For HTTPS Internal Services''':
<pre>
 
newservice.jb-vpn.uk {
If your internal service uses HTTPS, change the proxy_pass line:
reverse_proxy https://10.8.0.2:PORT {
<pre class="lang-nginx">
transport http {
proxy_pass https://10.8.0.2:PORT_NUMBER;
tls_insecure_skip_verify
}
header_up Host {host}
header_up X-Forwarded-Proto {scheme}
}
}
</pre>
</pre>


'''For Services Requiring Special Headers''':
Replace <code>PORT</code> with the internal port and ensure DNS points to the VPS.
 
Some services (like Plex) require additional headers. See [Service Examples](service-examples.md) for reference.


== Step 2: Enable the Site ==
== Step 2: Validate and reload ==
 
Create a symlink to enable the site:


<pre class="lang-bash">
<pre class="lang-bash">
sudo ln -s /etc/nginx/sites-available/newservice.jb-vpn.uk /etc/nginx/sites-enabled/newservice.jb-vpn.uk
caddy validate --config /etc/caddy/Caddyfile
systemctl reload caddy
</pre>
</pre>


== Step 3: Test Nginx Configuration ==
== Step 3: Verify connectivity ==
 
Always test the configuration before reloading:


<pre class="lang-bash">
<pre class="lang-bash">
sudo nginx -t
nslookup newservice.jb-vpn.uk
</pre>
curl -I https://newservice.jb-vpn.uk
 
'''Expected Output''':
<pre>
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
</pre>
 
'''If there are errors''': Fix them before proceeding. Common issues:
'' 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):
 
<pre class="lang-bash">
sudo systemctl reload nginx
</pre>
</pre>


== Step 5: Verify HTTP Access ==
For NAS backends, confirm VPN first:
 
Test that the service is accessible via HTTP:


<pre class="lang-bash">
<pre class="lang-bash">
curl -I http://newservice.jb-vpn.uk
ping -c 2 10.8.0.2
curl -sI -m 5 http://10.8.0.2:PORT | head -1
</pre>
</pre>


You should receive an HTTP response. If you get a connection error:
== Step 4: TLS ==
'' 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:
Caddy obtains and renews Let's Encrypt certificates automatically when:


<pre class="lang-bash">
* DNS for the hostname points to <code>87.106.61.62</code>
sudo certbot --nginx -d newservice.jb-vpn.uk --non-interactive --agree-tos --redirect --email admin@jb-vpn.uk
</pre>


'''What this does''':
* Ports 80 and 443 are reachable on the VPS
'' Requests SSL certificate from Let's Encrypt
'' Configures nginx for HTTPS
'' Sets up HTTP to HTTPS redirect
'' Configures automatic renewal


'''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
'' All functionality works as expected


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


To remove a service:
== Removing a service ==


= '''Disable the site''': =
# Remove the site block from <code>/etc/caddy/Caddyfile</code>
  <pre class="lang-bash">
# <code>caddy validate --config /etc/caddy/Caddyfile</code>
  sudo rm /etc/nginx/sites-enabled/service.jb-vpn.uk
# <code>systemctl reload caddy</code>
</pre>


= '''Test configuration''': =
== Related documentation ==
  <pre class="lang-bash">
  sudo nginx -t
</pre>


= '''Reload nginx''': =
* [Prerequisites Prerequisites]
  <pre class="lang-bash">
  sudo systemctl reload nginx
</pre>


= '''Optional - Remove configuration file''': =
* [Service Examples Service Examples]
  <pre class="lang-bash">
  sudo rm /etc/nginx/sites-available/service.jb-vpn.uk
</pre>


= '''Optional - Revoke SSL certificate''': =
* [Configuration Options Configuration Options]
  <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 ==
* [[Services:Current Services]]


'' [[Documentation:Prerequisites](Prerequisites|- Requirements before starting
'' [Configuration Options]])(configuration-options.md) - Advanced configuration
'' [Service Examples](service-examples.md) - Service-specific examples
'' [[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"