<commit_before># HTTPS-PORTAL

HTTPS-PORTAL is a fully automated HTTPS server powered by
[Nginx](http://nginx.org), [Let's Encrypt](https://letsencrypt.org) and
[Docker](https://www.docker.com). 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/](https://hub.docker.com/r/steveltn/https-portal/)

## Table of Contents

- [HTTPS-PORTAL](#https-portal)
  - [Prerequisite](#prerequisite)
  - [See It Work](#see-it-work)
  - [Quick Start](#quick-start)
  - [Features](#features)
    - [Test Locally](#test-locally)
    - [Redirections](#redirections)
    - [Automatic Container Discovery](#automatic-container-discovery)
    - [Hybrid Setup with Non-Dockerized Apps](#hybrid-setup-with-non-dockerized-apps)
    - [Multiple Domains](#multiple-domains)
    - [Multiple Upstreams](#multiple-upstreams)
    - [Serving Static Sites](#serving-static-sites)
    - [Share Certificates with Other Apps](#share-certificates-with-other-apps)
    - [HTTP Basic Auth](#http-basic-auth)
    - [Access Restriction](#access-restriction)
    - [Logging configuration](#logging-configuration)
    - [Debugging](#debugging)
    - [Other Configurations](#other-configurations)
    - [Internationalized Domain Names (IDN)](#internationalized-domain-names-idn)
  - [Advanced Usage](#advanced-usage)
    - [Configure Nginx through Environment Variables](#configure-nginx-through-environment-variables)
    - [Change Configuration Dynamically](#change-configuration-dynamically)
    - [Override Nginx Configuration Files](#override-nginx-configuration-files)
    - [Manually Set Private Key Length/Type](#manually-set-private-key-length-type)
  - [How It Works](#how-it-works)
  - [About Rate Limits of Let's Encrypt](#about-rate-limits-of-lets-encrypt)
  - [Troubleshooting](#troubleshooting)
  - [Credits](#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](https://docs.docker.com/engine/installation/) installed.
  In addition, [Docker Compose](https://docs.docker.com/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:

```yaml
version: '3'

services:
  https-portal:
    image: steveltn/https-portal:1
    ports:
      - '80:80'
      - '443:443'
    environment:
      DOMAINS: 'example.com'
      # STAGE: 'production' # Don't use production until staging works
    volumes:
      - https-portal-data:/var/lib/https-portal

volumes:
    https-portal-data: # Recommended, to avoid re-signing when upgrading HTTPS-PORTAL
```

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

## Quick Start

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

```yaml
version: '3'

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' # Don't use production until staging works
    # FORCE_RENEW: 'true'
  volumes: 
    - https-portal-data:/var/lib/https-portal

wordpress:
  image: wordpress
  links:
    - db:mysql

db:
  image: mariadb
  environment:
    MYSQL_ROOT_PASSWORD: '<<PASSWORD>>'

volumes:
  https-portal-data:
```

Run the `docker-compose up -d` command. A moment later you'll get a WordPress
running on [https://wordpress.example.com](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.

```yaml
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 to 127.0.0.1,

or

* set up DNSMasq on your computer/router. This method provides more flexibility.

or

* configure `DOMAINS: 'mysite.lvh.me` in docker-compose.yml instead of `example.com` (lvh.me has a wildcard DNS entry that resolves any second level name to 127.0.0.1) so than you can access https://mysite.lvh.me.

Once you are done testing, you can deploy your application stack to the server.

### Redirections

HTTPS-PORTAL support quick setup for redirections.

```yaml
https-portal:
  # ...<commit_msg>Modify README<commit_after># HTTPS-PORTAL

HTTPS-PORTAL is a fully automated HTTPS server powered by
[Nginx](http://nginx.org), [Let's Encrypt](https://letsencrypt.org) and
[Docker](https://www.docker.com). 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/](https://hub.docker.com/r/steveltn/https-portal/)

## Table of Contents

- [HTTPS-PORTAL](#https-portal)
  - [Prerequisite](#prerequisite)
  - [See It Work](#see-it-work)
  - [Quick Start](#quick-start)
  - [Features](#features)
    - [Test Locally](#test-locally)
    - [Redirections](#redirections)
    - [Automatic Container Discovery](#automatic-container-discovery)
    - [Hybrid Setup with Non-Dockerized Apps](#hybrid-setup-with-non-dockerized-apps)
    - [Multiple Domains](#multiple-domains)
    - [Multiple Upstreams](#multiple-upstreams)
    - [Serving Static Sites](#serving-static-sites)
    - [Share Certificates with Other Apps](#share-certificates-with-other-apps)
    - [HTTP Basic Auth](#http-basic-auth)
    - [Access Restriction](#access-restriction)
    - [Logging configuration](#logging-configuration)
    - [Debugging](#debugging)
    - [Other Configurations](#other-configurations)
    - [Internationalized Domain Names (IDN)](#internationalized-domain-names-idn)
  - [Advanced Usage](#advanced-usage)
    - [Configure Nginx through Environment Variables](#configure-nginx-through-environment-variables)
    - [Change Configuration Dynamically](#change-configuration-dynamically)
    - [Override Nginx Configuration Files](#override-nginx-configuration-files)
    - [Manually Set Private Key Length/Type](#manually-set-private-key-length-type)
  - [How It Works](#how-it-works)
  - [About Rate Limits of Let's Encrypt](#about-rate-limits-of-lets-encrypt)
  - [Troubleshooting](#troubleshooting)
  - [Credits](#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](https://docs.docker.com/engine/installation/) installed.
  In addition, [Docker Compose](https://docs.docker.com/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:

```yaml
version: '3'

services:
  https-portal:
    image: steveltn/https-portal:1
    ports:
      - '80:80'
      - '443:443'
    environment:
      DOMAINS: 'example.com'
      # STAGE: 'production' # Don't use production until staging works
    volumes:
      - https-portal-data:/var/lib/https-portal

volumes:
    https-portal-data: # Recommended, to avoid re-signing when upgrading HTTPS-PORTAL
```

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

## Quick Start

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

```yaml
version: '3'

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' # Don't use production until staging works
    # FORCE_RENEW: 'true'
  volumes: 
    - https-portal-data:/var/lib/https-portal

wordpress:
  image: wordpress
  links:
    - db:mysql

db:
  image: mariadb
  environment:
    MYSQL_ROOT_PASSWORD: '<<PASSWORD>>'

volumes:
  https-portal-data:
```

Run the `docker-compose up -d` command. A moment later you'll get a WordPress
running on [https://wordpress.example.com](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.

```yaml
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 to 12192.168.3.11 (or any other IP address pointing to your Docker host),

or

* set up DNSMasq on your computer/router. This method provides more flexibility.

or

* configure `DOMAINS: 'mysite.lvh.me` in `docker-compose.yml` instead of `example.com` (lvh.me is a wildcard DNS entry that resolves any second level name to 127.0.0.1) so than you can access https://mysite.lvh.me.

Once you are done testing, you can deploy your application stack to the server.

### Redirections

HTTPS-PORTAL support quick setup for redirections.

```yaml
https-portal:
  # ...
{'fraction_non_alphanumeric': 0.11131059245960502, 'fraction_numerical': 0.007779772591262717, 'mean_word_length': 3.9275484414490314, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 9, 'https://': 22, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 4, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5573934', 'n_tokens_mistral': 3803, 'n_tokens_neox': 3533, 'n_words': 1199}