These files create a Docker network using nginx-proxy as a reverse proxy, allowing multiple local domain names to use the same standard 80 or 443 ports.
For example, instead of having to configure each local domain with an unused port, such as yourdomain.example:8080
and yourdomain2.example:8081
, the reverse proxy takes care of the ports so you can use clean domain names, such as yourdomain.example
and yourdomain2.example
.
- In the parent directory where you want to store your Docker reverse proxy files (such as
/Users/Username/Projects/Assets/Docker/
), run:git clone [email protected]:jacobcassidy/docker-nginx-proxy-setup.git
. - Rename the cloned directory from
docker-nginx-proxy-setup
to the project name you want to use, such as nginx-proxy-base. - Open the Docker Desktop app so the Docker engine is on. (If you don't have the Docker Desktop app installed on your local machine, install it first.)
- In the nginx-proxy-base directory you cloned, run:
docker compose up -d
to create and start the Docker container.
You must add TLS certifications for each domain you want to use. This can be done quickly with the mkcert command line tool.
- Install mkcert
- Run:
mkcert -install
to create your local CA (this only needs to be done once). - In your nginx-proxy-base/certs/ directory, create a new cert with:
mkcert yourlocaldomain.tld
. Make sure you replace "yourlocaldomain.tld" with the local domain name you will use. - After mkcert creates your certs, rename them:
FROM TO yourlocaldomain.tld-key.pem yourlocaldomain.tld.key yourlocaldomain.tld.pem yourlocaldomain.tld.crt - If you use a TLD that is not .localhost (see note below), you must add the domain name to your local machine's hosts file. This can be done on macOS with:
sudo vim /etc/hosts
and adding127.0.0.1 yourlocaldomain.tld
to the list (make sure to replace yourlocaldomain.tld with your actual domain name).
Since cURL version 7.85.0, domains ending in .localhost can no longer resolve to an external IP (see: Curl localhost as a local host and Curl is not correctly resolving docker.localhost domain since version 7.85.0).
This causes issues when using .localhost with some services, such as PHP and WordPress, because they use the cURL command to connect with other services. For example, WordPress uses it for its internal REST API and loopback connections.
For this reason, I recommend using a different TLD for your local domains, such as .dockerhost or .local.
Project using older versions of cURL, such as found in PHP versions before 8.1, will not have this issue.
By default, cloning a Git repository, which you did above in step one of the installation instructions, will clone the original .git directory. Any changes you push will attempt to go to the [email protected]:jacobcassidy/docker-nginx-proxy-setup.git
repo, but you will get a permissions error, which is probably not what you want.
You have two options for using Git with your remote repository:
- You can keep the cloned Git intact and change the connected remote repo.
- You can remove the cloned Git repo and start with a clean repo.
- Check which remote Git repo is currently in use with:
git remote -v
. This should output:origin https://github.com/jacobcassidy/docker-nginx-proxy-setup.git (fetch) origin https://github.com/jacobcassidy/docker-nginx-proxy-setup.git (push)
- Change the remote repo used with:
git remote set-url origin <new-url>
. Make sure to replace<new-url>
with your actual GitHub URL, such as[email protected]:username/new-repository.git
orhttps://github.com/username/new-repository.git
. - Run
git remote -v
to confirm your remote Git URL was correctly updated.
- In your nginx-proxy-base directory, remove the cloned .git directory with:
rm -rf .git
. - Initialize a new local Git repository with:
git init
. - Connect your remote GitHub repo as usual.
When adding a new project to the nginx-proxy-network, keep the following in mind:
- You must include the nginx-proxy-network in the project. If your project uses a
compose.yaml
file, include the following network settings as a top-level element:networks: nginx-proxy-network: external: true backend:
- Don't include ports for your services running on port 80 or 443 because the nginx-proxy service will take care of them. Other services, such as databases, should still use ports as usual.
- If you're using port 443 for the HTTPS protocol, you must create and add the TLS certs for your local domains in the
/nginx-proxy-base/certs
directory, and add the domain names in your local machine's hosts file (see "Using HTTPS with local domains" instructions above).
Example projects that use the nginx-proxy-network include the Docker WordPress Setup and the Docker Nginx PHP-FPM Setup.
If you come across any issues, please feel free to report them here.