HTTPS-PORTAL

HTTPS-PORTAL is a fully automated HTTPS server powered by
Nginx, Let's Encrypt and
Docker. By using it, you can run any existing web
application over HTTPS, with only one extra line of configuration.

The SSL certificates are obtained, and renewed from Let's Encrypt
automatically.

Docker Hub page:
https://hub.docker.com/r/steveltn/https-portal/

Table of Contents

• HTTPS-PORTAL
  • Prerequisite
  • See It Work
  • Quick Start
  • Features
    • Test Locally
    • Redirections
    • Automatic Container Discovery
    • Hybrid Setup with Non-Dockerized Apps
    • Multiple Domains
    • Serving Static Sites
    • Share Certificates with Other Apps
    • HTTP Basic Auth
    • Access Restriction
  • Advanced Usage
    • Configure Nginx through Environment Variables
    • Override Nginx Configuration Files
  • How It Works
  • About Rate Limits of Let's Encrypt
  • Troubleshooting
  • Credits

Prerequisite

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 highly
  recommended, for it makes your life easier. Examples in our documents are
  mainly in Docker Compose format.
• Has all domains you're going to use in the following examples resolving to
  it.

Though it is good to have, knowledge about Docker is not required to use
HTTPS-PORTAL.

See It Work

Create a docker-compose.yml file with the following content in any directory
of your choice:

https-portal:
  image: steveltn/https-portal:1
  ports:
    - '80:80'
    - '443:443'
  environment:
    DOMAINS: 'example.com'
    # STAGE: 'production'

Run the docker-compose up command in the same directory. A moment later you'll
have a welcome page running in
https://example.com.

Quick Start

Here is a more real-world example: Create the file docker-compose.yml in another
directory:

https-portal:
  image: steveltn/https-portal:1
  ports:
    - '80:80'
    - '443:443'
  links:
    - wordpress
  restart: always
  environment:
    DOMAINS: 'wordpress.example.com -> http://wordpress:80'
    # STAGE: 'production'
    # FORCE_RENEW: 'true'

wordpress:
  image: wordpress
  links:
    - db:mysql

db:
  image: mariadb
  environment:
    MYSQL_ROOT_PASSWORD: '<a secure password>'

Run the docker-compose up -d command. A moment later you'll get a WordPress
running on https://wordpress.example.com.

In the example above, only the environment variables under the https-portal
section are HTTPS-PORTAL specific configurations. This time we added an extra
parameter -d, which will tell Docker Compose to run the apps defined in
docker-compose.yml in the background.

Note:

• STAGE is staging by default, which results in a test
  (untrusted) certificate from Let's Encrypt.
• wordpress is the hostname of WordPress container within HTTPS-PORTAL container. Usually you can use the service name of your WordPress container.

Features

Test Locally

You can test HTTPS-PORTAL with your application stack locally.

https-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 can
use it to test your docker-compose file. Make sure it works with your application
stack.

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 hosts file to have example.com resolving to your docker host,

or

• 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.

Redirections

HTTPS-PORTAL support quick setup for redirections.

https-portal:
  # ...
  environment:
    DOMAINS: 'example.com => https://target.example.com' # Notice it's "=>" instead of the normal "->"

All paths will be redirected to the target. E.g. https://example.com/foo/bar will be 301 redirected to https://target.example.com/foo/bar.

A common use case is to redirect www.example.com to example.com. Configure your DNS, make both www.example.com and example.com resolve to the HTTPS-PORTAL host, and use the following compose:

https-portal:
  # ...
  environment:
    DOMAINS: 'www.example.com => https://example.com' # Notice it's "=>" instead of the normal "->"

Automatic Container Discovery

WARNING: WE STRONGLY RECOMMEND AGAINST USING THIS FEATURE UNLESS ABSOLUTELY NECESSARY as exposing Docker socket to a container (even with :ro) essentially gives the container root access to your host OS. If you insist, verify the source code carefully. Read more

HTTPS-PORTAL is capable of discovering other Docker containers running on the
same 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 docker-compose.yml.

version: '2'

services:
  https-portal:
    # ...
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro # DANGEROUS, see the warning above

and launch one or more web applications with:

version: '2'

services:
  a-web-application:
    # ...
    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 host
without restarting HTTPS-PORTAL itself or interrupting any other application while
adding/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:

a-multi-port-web-application:
  # ...
  expose:
    - '80'
    - '8080'
  environment:
    VIRTUAL_HOST: example.com
    VIRTUAL_PORT: '8080'

Of course container discovery works in combination with ENV specified domains:

https-portal:
  # ...
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock:ro # DANGEROUS, see the warning above
  environment:
    DOMAINS: 'example.com -> http://upstream'

Hybrid Setup with Non-Dockerized Apps

Web applications that run directly on the host machine instead of in Docker
containers are available at dockerhost.

For instance, if an application accepts HTTP requests on port 8080 of the host
machine, you can start HTTPS-PORTAL by:

https-portal:
  # ...
  environment:
    DOMAINS: 'example.com -> http://dockerhost:8080'

Firewall settings

If you use a firewall like ufw, you
might need to allow communication from the container to your docker host machine.
You can check if ufw is active by executing ufw status.

If the command returns active, add the ufw rule to allow communication on port 8080 from HTTPS-PORTAL's container IP to the docker host IP on the port where the web application is reachable:

DOCKER_HOST_IP=`docker network inspect code_default --format='{{ .IPAM.Config}}'