This repo is a collection of configuration files/scripts for my server. This down here is a general explanation of how everything works. Every app's folder has a README.md with more specific information.
First of all, read a tiny little bit about docker and docker-compose if you don' t know what they are.
TL:DR -> Docker is a software to create containers, where we'll put our apps, Compose is a tool for defining and running multi-container Docker applications.
If you´re on a public server you probably want to piont them to a domain like mycoolapp.mycooldomain.com. The software used to do this is called a reverse proxy and there many of them, nginx, trafik, caddy etc. Linuxserver's swag docker is the main one used here; it gives us:
- free certificates: you get the green lock on your browser, and your web traffic is encrypted
- reverse proxy: you can host multiple apps on your domain and reach them with subdomain/subfolders
For every application you want to add, you need two files: a docker-compose.yml to install and configure it and a .conf for the Nginx reverse proxy.
Important: the instructions are for servers with domains, so go and get one or skip the Letsencrypt part.
Install Docker and Compose for your OS. Follow their instruction carefully to configure it the first time.
Create a new docker-compose.yml file under a Letsencrypt folder and paste the content from here in it. You need to fill it with your information. You can also check how mine is (more or less).
- TZ=Europe/London
Set your timezone here
- URL=yourdomain.url
Set your main domain here
- SUBDOMAINS=www,
Set your sub-domains here. These are the ones you want to provide https for, and they need to be the same used in the various Ngix .conf files. For example, if I want to install portainer and my portainer.subdomain.conf contains the line server_name portainer.*; I will need to set it as - SUBDOMAINS=www,portainer. They can be easily switched to anything you want, like server_name coffee.*; and - SUBDOMAINS=www,coffee, making it reachable under coffee.mycooldomain.com. Extra subdomains are not a problem. If you want to put your applications under a subfolder of your main domain, like mycooldomain.com/coffee, you don't need to add them under SUBDOMAINS. Subfolders are harder to set up so I´d avoid them where possible.
--e EMAIL=
You'll get some mails about certificate expiration, as they last 2/3 months. They'll be renewed automatically, so don't worry.
- /path/to/appdata/config:/config
This one is important: you'll add and remove from here the Ngix .conf files. I used .config:/config as a path, this means I'll get the config folder in the same directory as this docker-compose.yml.
If you don't need/don't know about the optional stuff, you can remove it.
I added to the default linuxserver.io compose file a network. Since Letsencrypt's container needs to be connected to the other containers, we have two ways to do this:
- put everything in the same docker-compose.yml file, a single network will be created and connect all of them
- manually choose a network and set it in every docker-compose.yml file
I'm using a single compose file because I didn't know yet about this when I first built the server, but I'm moving towards option 2.
Network creation under Letsencrypt/Swag compose file:
---
version: "2.1"
services:
letsencrypt:
...
...
networks:
- letsencrypt_default
networks:
letsencrypt_default:
driver: bridge
Network use in other compose files:
---
version: "2.1"
services:
portainer:
...
...
networks:
- letsencrypt_default
networks:
letsencrypt_default:
external: true
Run docker-compose up -d once to generate all the necessary files and the certificates. If you browse to mycooldomain.com you should see a work-in-progress message and a green lock.
If it does not work, you can check out logs with docker logs container_name and get the docker container name with docker ps
If your Letsencrypt container runs correctly, you should now have a config folder. Navigate to config/ngix/proxy-confs and check the available samples. You can also find them in this repo. To activate one of these, you can rename it, so it ends with .conf after you've modified it.
If you use one of the configuration files already in this folder, they're pretty much ready to go, there should be two versions for every app: a subdomain and a subfolder one. They will result in app.mycooldomain.com or mycooldomain.com/app, and please use only one of them.
For a subdomain config file these are the essential parameters:
server_name portainer.*;
Or
server_name portainer.mydomain.com;
if you have multiple domains on your server.
This will tell Nginx which subdomain should route the container stuff, can be changed without issues (remember to add it to SUBDOMAINS)
set $upstream_app portainer;
This will tell Nginx which container needs to be connected (its name is the one used in the compose file)
set $upstream_port 9000;
This will tell Nginx the port where the traffic needs to be routed inside the container
You can add many external apps by copying a sample .conf file and editing these three parameters.
You can get a list of Linuxserver's applications here or check their repositories on Github. Check the docker-compose section (like this), copy and paste it as explained before and we're almost ready.
Check the other apps section for info on other applications' collections.
Websites and Web-apps
You may want to host a site using this setup, or maybe a web-app is not available as Docker container but as an Html + CSS + javascript build. They can be easily added to ngix/letsencrypt:
- add to your SUBDOMAINS the subdomain as before
- drop the web-app under a folder in letsencrypt/config/www
- navigate to letsencrypt/config/ngix/site-confs
- create a .conf file with your app name (the default file here has some examples)
This is the my-mind.conf file for my-mynd:
server {
listen 443 ssl http2;
listen [::]:443 ssl http2;
root /config/www/my-mind;
index index.html index.htm index.php;
server_name my-mind.*;
include /config/nginx/ssl.conf;
client_max_body_size 0;
location / {
auth_basic "Restricted";
auth_basic_user_file /config/nginx/.htpasswd;
include /config/nginx/proxy.conf;
try_files $uri $uri/ /index.html /index.php?$args =404;
}
}
How to configure it:
root /config/www/my-mind;
Point this to the folder of your web-app containing the entry file (index.html, index.htm, index.php or whatever).
server_name my-mind.*;
As before, this is where you'll browse to access the app.
auth_basic "Restricted";
auth_basic_user_file /config/nginx/.htpasswd;
This is optional. It adds a password to access the app. Since many websites/web-apps do not have a login option, this can be used to restrict access.
If you decide to use this, you need to create the credentials, see here.
You have to run the command
docker exec -it letsencrypt htpasswd -c /config/nginx/.htpasswd <username>
and you'll be asked for a new password.
You'll also need to restart the Letsencrypt's container (but complete the configuration first).
More details on:
Your domain point to an IP address, for example, mysupercooldomain.com points to 64.98.145.30. But if you're using subdomains, you also need to make sure that those point to your IP, too.
To do this, find your DNS provider settings page and add a wildcard redirect (every subdomain will be redirected to your IP) or a redirect for every single subdomain.
Your DNS provider page should look like this:
Check on the internet where to find it and how to change it, look here for Namecheap.
Run this checklist:
- Letsencrypt docker-compose.yml configured and executed correctly
- ngix .conf renamed/configured under the
proxy-confsfolder - every app's docker-compose.yml configured
- ngix .conf configured under the
site-confsfolder and files dropped underconfig/wwwfor evey website/webapp - dns record ready
Run again docker-compose up -d for Letsencrypt docker-compose.yml and then for every other compose file (if any). You can now check every subdomain/subfolder.
- You can check the status of your containers with
docker psand their logs withdocker logs container_name - You can restart your containers with
docker restart container_name - Nginx logs are under our letsencrypt/config/log/nginx/ directory
- if you changed the DNS records, you may need to wait some time for them to propagate
When you start having more and more apps installed on your server, you may want to have a home to select the right one. There are specialized apps, such as Heimdall, or you can get a static page. On reddit, there are many of them with all the code included.
Using the images provided by linuxserver.io it's pretty easy to set up all the web-apps and services you want on your server.
External Docker images can be added almost as smoothly and usually require little configuration if any. You can check on github if the project has a docker-compose.yml file or go directly on the docker hub. Be careful of unofficial images on the hub, use the official ones where possible.
Awesome selfhosted is a curated list of app you can self-host. The easiest way to integrate them with your docker is by looking up on your favorite search engine "docker-compose appname"
NGINX Proxy Manager is a graphical tool to manage NGINX. You can avoid the swag/letsencrypt container using this. It's easy to use but you won´t learn anything about reverse proxies so you should start with swag first.