https://github.com/bwajtr/https-on-localhost-how-to
How to easily test any localhost website using a valid HTTPS protocol (run nginx SSL termination on a developer machine using docker compose)
https://github.com/bwajtr/https-on-localhost-how-to
docker-compose localhost mkcert nginx reverse-proxy ssl-certificates ssl-termination
Last synced: 3 months ago
JSON representation
How to easily test any localhost website using a valid HTTPS protocol (run nginx SSL termination on a developer machine using docker compose)
- Host: GitHub
- URL: https://github.com/bwajtr/https-on-localhost-how-to
- Owner: bwajtr
- License: mit
- Created: 2024-02-19T07:35:06.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-02-19T08:41:37.000Z (over 1 year ago)
- Last Synced: 2025-06-02T14:55:51.210Z (4 months ago)
- Topics: docker-compose, localhost, mkcert, nginx, reverse-proxy, ssl-certificates, ssl-termination
- Language: Shell
- Homepage:
- Size: 3.91 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
## How to easily test any localhost website using a valid HTTPS protocol
### What is this about?
You typically develop webapps using HTTP protocol, because it's simple to run and use e.g. on http://localhost:8080
But the app might behave differently when running using HTTPS in production.
Below are fairly simple steps that are needed to set up HTTPS protocol (HTTP/2 actually) for your webapp testing locally.
Advantages of the below approach:
- you don't have to change anything in your app at all
- the app is still accessible on http://localhost:8080 - so you can test it using HTTP and HTTPS at the same time
- it mimics a typical production setup, where the SSL termination is done before the request even reaches your app
### How it works?
We use `mkcert` tool to generate (and install) self-signed SSL certificates so your browser will trust them.
Then we use `docker compose` to startup `nginx` local server running on https://secure.localhost that will use those
certificates and simply redirect all traffic to your local webapp running on http://localhost:8080. In technical terms the `nginx` server
will perform SSL termination and acts as a reverse proxy to your local webapp.
### How to run it?
1. Clone this repository locally
2. Install Docker Desktop
3. Install mkcert (https://github.com/FiloSottile/mkcert#installation)
- this is a tool that we will use to generate certificates required to run HTTPS locally
- Note that it's not safe to share these certificates, it's better to generate them on your own
- see this article for more details: https://web.dev/articles/how-to-use-local-https
4. Go to `nginx/certs/` and run `generate-certs.sh` there (this is required just once)
- It will probably require your system admin password, so it can add generated root CA certificate to your system
- `cert.pem` and `key.pem` should be generated in `nginx/certs/` directory
- You may need to restart your browsers to changes to take effect
5. Run your webapp (so it is available at http://localhost:8080)
6. Run `docker compose up` in the root directory of this repository
- HTTPS proxy is now running, accessible at https://secure.localhost, it redirects all traffic to http://localhost:8080
7. You can now keep docker compose running, you can restart your application as you like
8. When you are done, run `docker compose down` to stop the proxy
### Troubleshooting
* I see `502 Bad Gateway` instead of my website
- Make sure your webapp is running on http://localhost:8080