git clone SteveLTN-https-portal_-_2018-09-14_19-52-39.bundle -b master
A fully automated HTTPS server powered by Nginx, Let's Encrypt and Docker.
The SSL certificates are obtained, and renewed from Let's Encryptautomatically.
Docker Hub page:https://hub.docker.com/r/steveltn/https-portal/
Table of Contents
- See It Work
- Quick Start
- Test Locally
- Automatic Container Discovery
- Hybrid Setup with Non-Dockerized Apps
- Multiple Domains
- Serving Static Sites
- Share Certificates with Other Apps
- HTTP Basic Auth
- Advanced Usage
- Configure Nginx through Environment Variables
- Override Nginx Configuration Files
- How It Works
- About Rate Limits of Let's Encrypt
HTTPS-PORTAL is shipped as a Docker image. To use it, you need a Linux machine(either local or remote host) which:
- Has 80 and 443 port available and exposed.
- Has Docker Engine installed.In addition, Docker Compose is highlyrecommended, for it makes your life easier. Examples in our documents aremainly in Docker Compose format.
- Has all domains you're going to use in the following examples resolving toit.
Though it is good to have, knowledge about Docker is not required to useHTTPS-PORTAL.
See It Work
docker-compose.yml file with the following content in any directoryof your choice:
yamlhttps-portal: image: steveltn/https-portal:1 ports: - '80:80' - '443:443' environment: DOMAINS: 'example.com' # STAGE: 'production'
docker-compose up command in the same directory. A moment later you'llhave a welcome page running inhttps://example.com.
Here is a more real-world example: Create the file
docker-compose.yml in anotherdirectory:
```yamlhttps-portal: image: steveltn/https-portal:1 ports: - '80:80' - '443:443' links: - wordpress restart: always environment: DOMAINS: 'wordpress.example.com -> http://wordpress' # STAGE: 'production' # FORCE_RENEW: 'true'
wordpress: image: wordpress links: - db:mysql
db: image: mariadb environment: MYSQLROOTPASSWORD: ''```
docker-compose up -d command. A moment later you'll get a WordPressrunning on https://wordpress.example.com.
In the example above, only the environment variables under the
https-portalsection are HTTPS-PORTAL specific configurations. This time we added an extraparameter
-d, which will tell Docker Compose to run the apps defined in
docker-compose.yml in the background.
staging by default, which results in a test(untrusted) certificate from Let's Encrypt.
You can test HTTPS-PORTAL with your application stack locally.
yamlhttps-portal: # ... environment: STAGE: local DOMAINS: 'example.com'
By doing this, HTTPS-PORTAL will create a self-signed certificate.This certificate is not likely to be trusted by your browser, but you canuse it to test your docker-compose file. Make sure it works with your applicationstack.
Note that HTTPS-PORTAL only listens to
example.com, as you specified in the compose file.In order to make HTTPS-PORTAL respond to your connection, you need to either:
- modify your
hostsfile to have
example.comresolving to your docker host,
- set up DNSMasq on your computer/router. This method provides more flexibility.
Once you are done testing, you can deploy your application stack to the server.
HTTPS-PORTAL support quick setup for redirections. It is deliberately made tosupport https targets only because otherwise it'd be against the idea of this project.
yamlhttps-portal: # ... environment: STAGE: local DOMAINS: 'example.com => target.example.com/foo/bar' # Notice it's "=>" instead of the normal "->"
Automatic Container Discovery
HTTPS-PORTAL is capable of discovering other Docker containers running on thesame host, as long as the Docker API socket is accessible within the container.
In order to make it so, launch HTTPS-PORTAL using the following
services: https-portal: # ... volumes: - /var/run/docker.sock:/var/run/docker.sock:ro```
and launch one or more web applications with:
services: a-web-application: # ... ports: - '8080:80' environment: # tell HTTPS-PORTAL to set up "example.com" VIRTUAL_HOST: example.com```
Caveat: Your web application must be created in the same network as HTTPS-PORTAL.
Note that here is no need to link your web service to HTTPS-PORTAL, and you shouldn't put
example.com in environment variable
DOMAINS of HTTP-PORTAL.
This feature allows you to deploy multiple web applications on the same hostwithout restarting HTTPS-PORTAL itself or interrupting any other application whileadding/removing web applications.
If your web service has more than one port exposed (mind that ports can be exposed in your web service Dockerfile),use the environment variable
VIRTUAL_PORT to specify which port accepts HTTP requests:
yamla-multi-port-web-application: # ... ports: - '8080:80' - '2222:22' environment: VIRTUAL_HOST: example.com VIRTUAL_PORT: '8080'
Of course container discovery works in combination with ENV specified domains:
yamlhttps-portal: # ... volumes: - /var/run/docker.sock:/var/run/docker.sock:ro environment: DOMAINS: 'example.com -> http://upstream'
Hybrid Setup with Non-Dockerized Apps
Web applications that run directly on the host machine instead of in Dockercontainers are available at
For instance, if an application accepts HTTP requests on port 8080 of the hostmachine, you can start HTTPS-PORTAL by:
yamlhttps-portal: # ... environment: DOMAINS: 'example.com -> http://dockerhost:8080'
You can specify multiple domains by splitting them with commas:
yamlhttps-portal: # ... environment: DOMAINS: 'wordpress.example.com -> http://wordpress, gitlab.example.com -> http://gitlab'
You can also specify the stage (
production) for each individual site, note that stages of individual sites overrides the global stage:
yamlDOMAINS: 'wordpress.example.com -> http://wordpress #local, gitlab.example.com #production'
Serving Static Sites
Instead of forwarding requests to web applications, HTTPS-PORTAL can also serve(multiple) static sites directly:
yamlhttps-portal: # ... environment: DOMAINS: 'hexo.example.com, octopress.example.com' volumes: - /data/https-portal/vhosts:/var/www/vhosts
After HTTPS-PORTAL is started, it will create corresponding sub-directories foreach virtual host in the
/data/https-portal/vhosts directory on the host machine:
yaml/data/https-portal/vhosts├── hexo.example.com│ └── index.html└── octopress.example.com └── index.html
You can place your own static files in this directory hierarchy, they will notbe overwritten. You need an
index.html to be served as the homepage.
Share Certificates with Other Apps
You can mount an arbitrary host directory to
/var/lib/https-portal as adata volume.
yamlhttps-portal: # ... volumes: - /data/ssl_certs:/var/lib/https-portal
Now your certificates are available in
/data/ssl_certs on your host.
HTTP Basic Auth
You can set up an HTTP Basic Auth easily. It is useful when you put the websiteonline but don't want to open it to public until ready.
In your docker-compose file:
yamlhttps-portal: # ... environment: DOMAINS: 'username:firstname.lastname@example.org -> '
Configure Nginx through Environment Variables
There are several additional environment variables that you can use to config Nginx.They correspond to the configuration options that you would normally supply in
nginx.conf.The following are the config keys with default values:
WORKER_PROCESSES=1WORKER_CONNECTIONS=1024KEEPALIVE_TIMEOUT=65GZIP=onSERVER_TOKENS=offSERVER_NAMES_HASH_MAX_SIZE=512SERVER_NAMES_HASH_BUCKET_SIZE=32 # defaults to 32 or 64 based on your CPUCLIENT_MAX_BODY_SIZE=1M # 0 disables checking request body sizePROXY_BUFFERS="8 4k" # Either 4k or 8k depending on the platformPROXY_BUFFER_SIZE="4k" # Either 4k or 8k depending on the platformRESOLVER="Your custom solver string"PROXY_CONNECT_TIMEOUT=60;PROXY_SEND_TIMEOUT=60;PROXY_READ_TIMEOUT=60;ACCESS_LOG=off;
You can also add
to make HTTPS-PORTAL proxy WEBSOCKET connections.
To avoid nginx DNS caching activate dynamic upstream
RESOLVER="127.0.0.11 ipv6=off valid=30s"DYNAMIC_UPSTREAM=true
Override Nginx Configuration Files
You can override default nginx settings by providing a config segment ofnginx.conf containing a valid
server block. The custom nginx configurationsare ERB templates and will berendered before usage.
For instance, to override both HTTPS and HTTP settings for
my.example.com,you can launch HTTPS-PORTAL by:
yamlhttps-portal: # ... volumes: - /path/to/http_config:/var/lib/nginx-conf/my.example.com.conf.erb:ro - /path/to/https_config:/var/lib/nginx-conf/my.example.com.ssl.conf.erb:ro
Another example can be found here.
If you want to make an Nginx configuration that will be used by all sites, you can overwrite
/var/lib/nginx-conf/default.ssl.conf.erb. These two files will be propagated to each site if the site-specific configuration files are not provided.
Manually Set RSA Private Key Length
By default, HTTPS-PORTAL generate
2048 bits long RSA private key.
However, you can manually set RSA private key length (
openssl genrsa command) through
NUMBITS environment variable.
yamlhttps-portal: # ... environment: NUMBITS: '4096'
How It Works
- obtains an SSL certificate for each of your subdomains fromLet's Encrypt.
- configures Nginx to use HTTPS (and force HTTPS by redirecting HTTP to HTTPS)
- sets up a cron job that checks your certificates every week, and renew them.if they expire in 30 days.
About Rate Limits of Let's Encrypt
Let's Encrypt's service is rate limited to ensure fair usage. Please familiarizeyourself with the various ratelimits. This documentation page isthe authoritative source for the current rate limit values.
For most people the most important rate limits are:
- 5 failed validation attempts per hour
- 50 certificates per registered domain per week
If you want to use HTTPS for multiple sub-domains with a single certificateLet's Encrypt supports putting up to 100 domains in one certificate, however itcan require careful planning and is hard to automate. So in HTTPS-PORTAL we onlydeal with single domain name certificates.
HTTPS-PORTAL stores your certificates in a data volume and will not re-signcertificates until 30 days before expiration if a valid certificate is found(you can force renew certificates by using
FORCE_RENEW: 'true' environmentvariable). However if you play around with the image a lot, you can hit thelimit. That's why
staging by default, and thus we use theLet's Encrypt staging server. When you have finished your experiments and feeleverything is good, you can switch to production mode with
Upload date: 2015-12-14
- 2018-09-14 19:52:39
- Internet Archive Python library 1.7.7
- iagitup - v1.0