Skip to content

Commit 40f472c

Browse files
evertramosevertramos
authored
Update README.md
1 parent afde529 commit 40f472c

File tree

1 file changed

+33
-203
lines changed

1 file changed

+33
-203
lines changed

‎.github/README.md‎

Lines changed: 33 additions & 203 deletions
Original file line numberDiff line numberDiff line change
@@ -1,237 +1,67 @@
11

22
# NGINX Proxy Automation 🔥
33

4-
## What this project does
4+
Automate your server with this proxy! ❤️
55

6-
This script will _power up_ your new server with the [*nginx-proxy*](https://github.com/nginx-proxy/nginx-proxy), where you will be able to host multiple sites,
7-
auto renewing Let´s Encrypt certificates! ❤️
6+
<p align="center">
7+
<a target="_blank" href="https://docs.docker.com/"><img src="https://img.shields.io/badge/Docker-2CA5E0?style=for-the-badge&logo=docker&logoColor=white" /></a>
8+
<a target="_blank" href="https://docs.nginx.com/"><img src="https://img.shields.io/badge/Nginx-009639?style=for-the-badge&logo=nginx&logoColor=white" /></a>
9+
<a target="_blank" href="https://developer.wordpress.org/"><img src="https://img.shields.io/badge/Wordpress-21759B?style=for-the-badge&logo=wordpress&logoColor=white" /></a>
10+
</p>
11+
<p align="center">
12+
<a target="_blank" href="https://letsencrypt.org/docs/"><img src="https://img.shields.io/badge/Secured_by-Let's_Encrypt-blue.svg?logo=let%E2%80%99s-encrypt" /></a>
13+
</p>
814

9-
Something like:
15+
<p align="center">
16+
<img src="https://github.com/evertramos/images/raw/master/webproxy.jpg" />
17+
</p>
1018

11-
![Web Proxy environment](https://github.com/evertramos/images/raw/master/webproxy.jpg)
19+
## How to start
20+
[![shell script](https://img.shields.io/badge/Shell_Script-121011?style=for-the-badge&logo=gnu-bash&logoColor=white)](https://github.com/evertramos)
1221

13-
We strongly recommend you (please do! 🙏) to read all documentation before starting in production as well as the [nginx-proxy docs](https://github.com/nginx-proxy/nginx-proxy).
1422

15-
> To access the previous version of this project please access [version 0.4](https://github.com/evertramos/nginx-proxy-automation/tree/v0.4).
16-
17-
### Upgrading from previous version
18-
19-
If you are upgrading from the previous version please follow the guide below carefully:
20-
21-
https://github.com/evertramos/nginx-proxy-automation/blob/master/docs/upgrade-guide.md
22-
23-
## Video Tutorial
24-
25-
I made a 5 minutes tutorial video to walk you through this project:
26-
27-
Click [here](https://www.youtube.com/watch?v=E9BtHVr_v9I) to access the video or click the image below:
28-
29-
[![NGINX-Proxy-Automation](https://img.youtube.com/vi/E9BtHVr_v9I/0.jpg)](https://www.youtube.com/watch?v=E9BtHVr_v9I)
30-
31-
## Prerequisites
32-
33-
1. 🐧 Linux! (just in case...)
34-
35-
> Please check all requirements at [requirements](/docs/requirements.md).
36-
37-
In order to use this compose file (docker-compose.yml) you must have:
38-
39-
2. 🐋 Docker installed (https://docs.docker.com/engine/installation/)
40-
41-
3. Docker-compose installed (https://docs.docker.com/compose/install/)
42-
43-
> I have an [easy-server](https://github.com/evertramos/easy-server) for myself which I use to install
44-
> docker and docker-compose in new servers and some aliases and other stuff. Feel free to use it, **but**
45-
> it is not related to this repo and maintainance it's for my own use only. Check './install/docker' folder.
46-
47-
Also, you will need to make sure you have:
48-
49-
4. Port 80 and 443 available for binding - which means apache/nginx or other web services should not be
50-
running in your server
51-
52-
5. Server must be accessible by a public IP address
53-
54-
## How to use it
55-
56-
1. Clone this repository **using the option _--recurse-submodules_**:
23+
1. Clone this repository using the option **_--recurse-submodules_**
5724

5825
```bash
59-
$ git clone --recurse-submodules https://github.com/evertramos/nginx-proxy-automation.git proxy
26+
git clone --recurse-submodules https://github.com/evertramos/nginx-proxy-automation.git proxy
6027
```
6128

62-
> Make sure you use the option '--recurse-submodules' once we use an external module in this project, please check
63-
> [basescript](https://github.com/evertramos/basescript)
29+
We use submodule for [basescript](https://github.com/evertramos/basescript)
6430

65-
> Please note we use 'proxy' as folder at the end. But you can change it to whatever fits you better
66-
67-
2. 🚀 Run the script 'fresh_start.sh'
31+
2. 🚀 Run the script 'fresh_start.sh' from the _./proxy/bin_ folder
6832

6933
```bash
70-
$ cd proxy/bin
71-
$ ./fresh-start.sh
72-
```
73-
This script will walk you through all config process.
74-
75-
When it finishes you are good to go! :checkered_flag:
76-
77-
> ✈️ If you are in a 'hurry' just run `$ ./fresh-start.sh --yes -e your_email@domain --skip-docker-image-check`
78-
79-
> ⚠️ You can check all available options to run the script `$ ./fresh-start.sh --help`
80-
81-
> 🗒️ From version _v0.3_ the script will output logs to _/var/log/basescript.log_
82-
83-
3. Fire your new site with the following options:
84-
85-
```yaml
86-
VIRTUAL_HOST=your.domain.com
87-
LETSENCRYPT_HOST=your.domain.com
88-
[email protected]
89-
NETWORK=proxy
90-
```
91-
92-
The fresh start script asked you for the proxy network name if you changed set a name differente from
93-
the default please update the option *'NETWORK'* in the examples below before running it.
94-
95-
- Simple site without Let's Encrypt certificate
96-
```bash
97-
$ docker run -d -e VIRTUAL_HOST=your.domain.com \
98-
--network=proxy \
99-
--name my_app \
100-
httpd:alpine
101-
```
102-
103-
- To have SSL in your web/app you must add the option `-e LETSENCRYPT_HOST=your.domain.com`, as follow:
104-
105-
```bash
106-
$ docker run -d -e VIRTUAL_HOST=your.domain.com \
107-
-e LETSENCRYPT_HOST=your.domain.com \
108-
-e [email protected] \
109-
--network=proxy \
110-
--name my_app \
111-
httpd:alpine
34+
cd proxy/bin && ./fresh-start.sh --yes -e your_email@domain --skip-docker-image-check
11235
```
11336

114-
> You don´t need to open port *443* in your container, the certificate validation is managed by the web proxy
115-
116-
> Please note that when running a new container to generate certificates with Let's Encrypt
117-
> (`-e LETSENCRYPT_HOST=your.domain.com`), it may take a few minutes
37+
Update the email above with your real e-mail address
11838

119-
120-
## Further Options
121-
122-
1. Basic Authentication Support
123-
124-
In order to be able to secure your virtual host with basic authentication, you must create a htpasswd file
125-
within `${NGINX_FILES_PATH}/htpasswd/${VIRTUAL_HOST}` via:
126-
127-
```bash
128-
$ sudo sh -c "echo -n '[username]:' >> ${NGINX_FILES_PATH}/htpasswd/${VIRTUAL_HOST}"
129-
$ sudo sh -c "openssl passwd -apr1 >> ${NGINX_FILES_PATH}/htpasswd/${VIRTUAL_HOST}"
130-
```
131-
132-
> Please replace the `${NGINX_FILES_PATH}` with real path to information, replace `[username]` with your username and `${VIRTUAL_HOST}` with your host's domain. You will be prompted for a password.
133-
134-
2. Using different networks
135-
136-
If you want to use more than one network to better organize your environment you could set the option `SERVICE_NETWORK` in our `.env.sample` or you can just create your own network and attach all your containers as of:
137-
138-
```bash
139-
docker network create myownnetwork
140-
docker network connect myownnetwork nginx-web
141-
docker network connect myownnetwork nginx-gen
142-
docker network connect myownnetwork nginx-letsencrypt
143-
```
144-
145-
3. Ports
146-
147-
If your service container runs on port 8545 you probably will need to add the `VIRTUAL_PORT` environment variable to your container,
148-
in the `docker-compose.yml`, so it can be proxied, as of:
149-
150-
```bash
151-
parity
152-
image: parity/parity:v1.8.9
153-
[...]
154-
environment:
155-
[...]
156-
VIRTUAL_PORT: 8545
157-
```
158-
159-
Or as of below:
160-
161-
```bash
162-
docker run [...] -e VIRTUAL_PORT=8545 [...]
163-
```
164-
165-
4. Restarting proxy container
166-
167-
In some cases you will need to restart the proxy in order to read, as an example, the Basic Auth, if you set it after your service container is already up and running. So, the way I use to restart the proxy (NGINX) is as following, which has no downtime:
168-
169-
```bash
170-
docker exec -it ${NGINX_WEB} nginx -s reload
171-
```
172-
173-
Where *${NGINX_WEB}* is your proxy container name, which in the original `.env` file is set as *nginx-web*.
174-
175-
176-
## Testing nginx-proxy
177-
178-
1. Run the script `test.sh` informing your domain already configured in your DNS to point out to your server as follow:
179-
180-
```bash
181-
./test.sh your.domain.com
182-
```
183-
184-
or simply run:
39+
3. 🧪 Test the proxy
18540

18641
```bash
18742
docker run -dit -e VIRTUAL_HOST=your.domain.com --network=webproxy --name test-web httpd:alpine
18843
```
189-
190-
> If you want to test the Let's Encrypt certificate as well use `ssl_test.sh your.domain.com`
191-
192-
Access your browser with your domain!
193-
194-
To stop and remove your test container run our `stop.sh` script:
195-
44+
or simply run:
19645
```bash
197-
./stop.sh
46+
./test.sh your.domain.com
19847
```
19948

200-
Or simply run:
201-
202-
```bash
203-
docker stop test-web && docker rm test-web
204-
```
49+
Update the lines above with your domain name which must have the DNS poiting to your public IP address in your server
20550

206-
## **PRODUCTION** ⚠️ [IMPORTANT]
51+
## Video Tutorial
20752

208-
If you are using this project in production enviroment, check all license involved and consider the following recomendation:
53+
I made a 5 minutes tutorial video to walk you through this project:
20954

210-
- [rootless docker](https://docs.docker.com/engine/security/rootless/)
211-
- [docker compose files](https://docs.docker.com/compose/production/)
55+
[![youtube](https://img.shields.io/badge/YouTube-FF0000?style=for-the-badge&logo=youtube&logoColor=white)](https://www.youtube.com/watch?v=E9BtHVr_v9I)
21256

213-
## Other projects using nginx-proxy
214-
Following are links to docker containers using this web proxy:
215-
1. [docker-wordpress-letsencrypt](https://github.com/evertramos/docker-wordpress-letsencrypt)
216-
2. [docker-portainer-letsencrypt](https://github.com/evertramos/docker-portainer-letsencrypt)
217-
3. [docker-nextcloud-letsencrypt](https://github.com/evertramos/docker-nextcloud-letsencrypt)
218-
4. [docker-registry-letsencrypt](https://github.com/evertramos/docker-registry-letsencrypt)
219-
5. [gitlab-docker-letsencrypt](https://github.com/steevepay/gitlab-docker-letsencrypt)
220-
6. [docker-webtrees-letsencrypt](https://github.com/mstroppel/docker-webtrees-letsencrypt)
57+
[![NGINX-Proxy-Automation](https://img.youtube.com/vi/E9BtHVr_v9I/0.jpg)](https://www.youtube.com/watch?v=E9BtHVr_v9I)
22158

222-
## Running this Proxy on a Synology NAS
223-
Please checkout this [howto](https://github.com/evertramos/nginx-proxy-automation/blob/master/docs/HOWTO-Synlogy.md).
59+
## Further information
22460

225-
## Credits
226-
Without the projects below this proxy would be impossible:
227-
- [nginx-proxy](https://github.com/nginx-proxy/nginx-proxy) by [@jwilder](https://github.com/jwilder)
228-
- [docker-gen](https://github.com/jwilder/docker-gen) by [@jwilder](https://github.com/jwilder)
229-
- [docker-letsencrypt-nginx-proxy-companion](https://github.com/JrCs/docker-letsencrypt-nginx-proxy-companion) by [@JrCs](https://github.com/JrCs)
61+
For more instalation details please [click here](/docs/).
23062

23163
## Supporting ♥️
232-
In case you are willing to support this project, check:
233-
- [Patreon (evertramos)](https://www.patreon.com/evertramos)
234-
- [Open Collective (nginx-proxy-automation)](https://opencollective.com/nginx-proxy-automation)
64+
[![Patreon](https://img.shields.io/badge/Patreon-F96854?style=for-the-badge&logo=patreon&logoColor=white)](https://www.patreon.com/evertramos)
65+
[![image](https://img.shields.io/badge/picpay-21C25E?style=for-the-badge&logo=picpay&logoColor=white)](https://picpay.me/evert.ramos)
23566

236-
## List of all supporters
237-
Please access the page [Supporters](https://github.com/evertramos/evertramos/blob/main/pages/supporters.md).
67+
[List of all supporters](https://github.com/evertramos/evertramos/blob/main/pages/supporters.md).

0 commit comments

Comments
 (0)