|Number of watchers on Github||571|
|Number of open issues||3|
|Average time to close an issue||11 days|
|Average time to merge a PR||2 days|
|Open pull requests||5+|
|Closed pull requests||6+|
|Last commit||over 2 years ago|
|Repo Created||almost 5 years ago|
|Repo Last Updated||over 2 years ago|
|Organization / Author||steveltn|
|Do you use https-portal? Leave a review!|
|View open issues (3)|
|View https-portal activity|
|View on github|
|Book a Mock Interview With Me (Silicon Valley Engineering Leader, 100s of interviews conducted)|
Software engineers: It's time to get promoted. Starting NOW! Subscribe to my mailing list and I will equip you with tools, tips and actionable advice to grow in your career.
The SSL certificates are obtained, and renewed from Let's Encrypt automatically.
Docker Hub page: https://hub.docker.com/r/steveltn/https-portal/
HTTPS-PORTAL is shipped as a Docker image. To use it, you need a Linux machine (either local or remote host) which:
Though it is good to have, knowledge about Docker is not required to use HTTPS-PORTAL.
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'
docker-compose up command in the same directory. A moment later you'll
have a welcome page running in
Here is a more real-world example: Create the file
docker-compose.yml in another
https-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: MYSQL_ROOT_PASSWORD: '<a secure password>'
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
section are HTTPS-PORTAL specific configurations. This time we added an extra
-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.
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:
hostsfile to have
example.comresolving to your docker host,
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 to support https targets only because otherwise it'd be against the idea of this project.
https-portal: # ... environment: STAGE: local DOMAINS: 'example.com => target.example.com/foo/bar' # Notice it's "=>" instead of the normal "->"
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
version: '2' services: https-portal: # ... volumes: - /var/run/docker.sock:/var/run/docker.sock:ro
and launch one or more web applications with:
version: '2' 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 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: # ... ports: - '8080:80' - '2222:22' 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 environment: DOMAINS: 'example.com -> http://upstream'
Web applications that run directly on the host machine instead of in Docker
containers are available at
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'
You can specify multiple domains by splitting them with commas:
https-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:
DOMAINS: 'wordpress.example.com -> http://wordpress #local, gitlab.example.com #production'
Instead of forwarding requests to web applications, HTTPS-PORTAL can also serve (multiple) static sites directly:
https-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 for
each virtual host in the
/data/https-portal/vhosts directory on the host machine:
/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 not
be overwritten. You need an
index.html to be served as the homepage.
You can mount an arbitrary host directory to
/var/lib/https-portal as a
https-portal: # ... volumes: - /data/ssl_certs:/var/lib/https-portal
Now your certificates are available in
/data/ssl_certs on your host.
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
The following are the config keys with default values:
WORKER_PROCESSES=1 WORKER_CONNECTIONS=1024 KEEPALIVE_TIMEOUT=65 GZIP=on SERVER_TOKENS=off SERVER_NAMES_HASH_MAX_SIZE=512 SERVER_NAMES_HASH_BUCKET_SIZE=32 # defaults to 32 or 64 based on your CPU CLIENT_MAX_BODY_SIZE=1M # 0 disables checking request body size PROXY_BUFFERS="8 4k" # Either 4k or 8k depending on the platform PROXY_BUFFER_SIZE="4k" # Either 4k or 8k depending on the platform RESOLVER="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
You can override default nginx settings by providing a config segment of
nginx.conf containing a valid
server block. The custom nginx configurations
are ERB templates and will be
rendered before usage.
For instance, to override both HTTPS and HTTP settings for
you can launch HTTPS-PORTAL by:
https-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.
The former is not usually a problem, however the latter could be, if you want to apply certificates for multiple sub-domains on a single domain. Let's Encrypt does support SAN certificates, however it requires careful planning and is hard to automate. So in HTTPS-PORTAL we only deal with CN certificates.
HTTPS-PORTAL stores your certificates in a data volume and will not re-sign
certificates until 30 days before expiration if a valid certificate is found
(you can force renew certificates by using
FORCE_RENEW: 'true' environment
variable). However if you play around with the image a lot, you can hit the
limit. That's why
staging by default, and thus we use the
Let's Encrypt staging server. When you have finished your experiments and feel
everything is good, you can switch to production mode with
According to Let's Encrypt, the restrictions will be loosened over time.
Fix the issue where cron jobs don't get environment variables.
dockerhostupstream didn't work.