Production Ready: pesde registry

Easily start up a pesde registry with this docker stack.

Warning

This guide is not conclusive. Please read the respective wikis on setting up the various tools used in this setup if you have any issues. I will not help with server setup, configuration, etc.

Installation

1. Getting a server - Free Oracle Cloud

   You can start for free via Oracle Cloud's free tier, giving you a free 24/7 ARM 4 OCPU, 24 GB RAM VM with 50 GB of storage space. This should be enough for most of your needs. However, getting a server can be difficult since there's limited spaces. To get around that, you can use a script to automatically try to get a server each minute. You can view it here.

2. Domain registration - Namecheap

   You need a domain name for this, any will work. From my experience, xyz TLDs are the cheapest at around $1 for the first year.

3. Protection - Cloudflare

   I strongly recommend you use Cloudflare to protect your servers from DDoS and attacks. View guides online for setting this up for your specific registrar. You need to create an origin server certificate and private key then put them on the server in the following directories. After that, you can enable Strict mdoe.

   • Certificate: /etc/ssl/certs/${ROOT_DOMAIN}.crt
   • Private Key: /etc/ssl/private/${ROOT_DOMAIN}.key

4. Protection - Hardening access

   A simple way to protect your server is to only allow Cloudflare IPs to access your server. The linked script automatically adds the needed iptables rules for you. However, you need to save it manually. These rules should make it so the ports for HTTP and HTTPS can only be accessed via Cloudflare. Other ports will remain open like normal.

   NOTE: If you are using Oracle Cloud, you need to use firewall-cmd instead, and disable iptables for Docker.

5. Protection - Other

   You can view more recommended things in the linked guide which covers making a new user and hardening SSH. I recommend you make a user for traefik and another user for the pesde registry itself.

6. CD (Optional) - Video 1, Video 2

   Dreams of Code has some great videos showing you further setup on the CD and things like docker context and docker stack. The CD will let you automatically make changes to the configuration on GitHub and see them deployed onto the server. I have already put the workflow here. If you want to use it, follow Video 1 by creating the DEPLOY_SSH_PRIVATE_KEY secret and setting the DEPLOY_HOST inside of the workflow file.

Configuration

Each folder (pesde and traefik) have their respective .env.template files. Simply make a copy of them, and edit the configuration to your liking.

Note

You shouldn't need to edit any other files but the environment files. Edit other files with caution.

Creating environment files from template

1. cd into each directory

   cd pesde
   

   cd traefik
   

2. Make a copy of the templates

   cp .env.template .env
   

3. Edit the template environment file to your liking

   nano .env
   

   You can use CTRL + X to save in nano.

Editing the environment files

In each template file, I've put the minimal recommended variables. I have also linked to the respective guides on additional variables you can put.

For the pesde configuration, I strongly recommend making a new GitHub user and the password must be a PAT. Make sure the user has at least push permissions to the index repository.

For the traefik configuration, you're asked for some Google API details. This makes your traefik instance more secure by adding a strong OAuth allowlist on accessing critical parts like the dashboard and whoami. You can view the official guide on setup here.

Adding your Cloudflare certificates

1. Grab your origin server certificate and private key from Cloudflare
2. Create a new folder inside traefik/certs
3. Create a file called ssl_public_key.crt and put your certificate there
4. Create a file called ssl_private_key.pem and put your private key there

Making the index repository

The index is a repository that contains metadata about all the packages in the registry. You can view the official guide on making it here.

Running

About docker context and swarm

Docker provides some useful tools for remote deployment. Docker context lets you run docker commands on your computer, as if they were on another host. On the other hand, Docker swarm is like kubernetes-lite. When combined, we can perform the entire deployment on your home computer, without needing to SSH into the remote computer.

Initialising the docker context

To start, create a new context, replacing USERNAME and IP_ADDRESS_OR_DOMAIN

docker context create pesde-reg --docker "host=ssh://USERNAME@IP_ADDRESS_OR_DOMAIN"

Then, use the context.

docker context use pesde-reg

Initialising the docker swarm

Simply run this command. Note that the output of this command can be retrieved at any time, so you can safely dismiss it!

docker swarm init

Deployment

Finally, you can run the entire stack with these commands, assuming you're cd into the respective directory on the server

docker stack deploy -c docker-stack.yaml traefik

docker stack deploy -c docker-stack.yaml pesde

Alternatively, you can also deploy via GitHub actions as mentioned in step 6 of installation.