Skip to main content

Caddy

To host websites on NX3, Caddy is highly recommended due to its' easy configuration, and the ability to automatically acquire SSL certificates for your websites using a different directory URL.

Install Caddy

To install Caddy it is recommended to follow the instructions available here.

Configure Caddy

You have many options to configure Caddy. You can make requests to the API, use the command line tools, and/or load configuration files from the /etc/caddy directory. For this tutorial, we'll be loading configuration files.

The default Caddyfile is as follows:

# /etc/caddy/Caddyfile

:80 {
	# Set this path to your site's directory.
	root * /usr/share/caddy

	# Enable the static file server.
	file_server

	# Another common task is to set up a reverse proxy:
	# reverse_proxy localhost:8080

	# Or serve a PHP site through php-fpm:
	# php_fastcgi localhost:9000
}

In order to dynamically load new configuration files we'll create two new directories:

mkdir -p /etc/caddy/sites-{available,enabled}

The sites-available directory is where we will store all of our configurations, and the sites-enabled directory is where we will link configurations we wish to be enabled on the server. This way, we have a staging directory for our configuration files.

To make use of these directories, we will modify the Caddyfile as follows:

# /etc/caddy/Caddyfile

import /etc/caddy/enabled-sites/*.caddy

You'll notice that we're adding a .caddy extension onto the Caddyfiles we'll create in the future, this is just to distinguish any additional files in the directory from our configurations.

From here, it's as easy as creating a new file for your site (example.nx3)

# /etc/caddy/sites-available/example.nx3.caddy

http://example.nx3 {
  	root * /usr/share/caddy

	file_server
}

I like to organize my files as the domain name + .caddy, but you can name yours in any way that makes sense to you.

From here we need to link the config to our sites-enabled directory, and reload the Caddy service:

sudo ln -s /etc/caddy/sites-available/example.nx3.caddy /etc/caddy/sites-enabled/example.nx3.caddy
sudo systemctl reload caddy
Reverse Proxy

If you prefer for your site to be a reverse proxy of another service instead, you can create your file as follows:

# /etc/caddy/sites-available/example.nx3.caddy

http://example.nx3 {
  reverse_proxy http://localhost:3000 # Replace with address to your service
}

All other steps are the same.

After that, you should attempt to navigate to your new site!

SSL Setup

As we're living inside of a walled garden environment, standard SSL certificates from somewhere like LetsEncrypt won't be able to be issued. For this purpose, there is an ACME server running on https://ca.info.nx3, and Caddy can be configured to use it as a certificate source.

To begin, you need to get the root certificate from the server (assuming you have the step-cli installed)

step ca bootstrap --ca-url https://ca.info.nx3 --fingerprint a828817e7d6592cdcf7260fe22bcd88fcea402fcdec5dd77cc48a1fa64c82a30
# Optional step, not required to acquire certificates
step ca certificate install /path/to/root_ca.crt

From there, you need to copy the root certificate to the /etc/caddy directory for ease of use:

cp /path/to/root_ca.crt /etc/caddy/nx3_ca.crt

If you do not plan on hosting public-internet (non NX3) services on this Caddy instance, you may configure the CA globally via the /etc/caddy/Caddyfile:

# /etc/caddy/Caddyfile

# Global Initialization (Top of file)
{
  # Initialize the NX3 CA
  email email@example.com
  acme_ca https://ca.info.nx3/acme/acme/directory
  acme_ca_root /etc/caddy/nx3_ca.crt
}

# ... Rest of configuration

If you prefer to do this on a domain-by-domain basis, you may do so by including this in your domain config:

https://example.nx3 {
  tls {
    ca https://ca.info.nx3/acme/acme/directory
    ca_root /etc/caddy/nx3_ca.crt
  }

  reverse_proxy http://127.0.0.1:3000
}

After configuring the CA, all you need to do is change any http://domain.name to https://domain.name

And just like that! You have SSL available on your websites!

Back to top