From 4e0c8caf40670686a41972cb7ef54d3cecce6638 Mon Sep 17 00:00:00 2001 From: Jeff Kleinhenz Date: Fri, 3 Jan 2020 14:10:30 -0600 Subject: [PATCH] updated README and all Pi instructions. --- README.md | 9 +- doc/Raspberry Pi-INSTALL.md | 157 +++++++++++++++++++++++++++++ doc/rpi-example/config.json | 10 ++ doc/rpi-example/docker-compose.yml | 29 ++++++ 4 files changed, 204 insertions(+), 1 deletion(-) create mode 100644 doc/Raspberry Pi-INSTALL.md create mode 100644 doc/rpi-example/config.json create mode 100644 doc/rpi-example/docker-compose.yml diff --git a/README.md b/README.md index a0270ba3..43995d2b 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,11 @@ This project comes as a pre-built docker image that enables you to easily forward to your websites running at home or otherwise, including free SSL, without having to know too much about Nginx or Letsencrypt. +## Credit Where it's Due +@jc21 +@talondnb +jc21/nginx-proxy-manager Issue #146, #269 + ## Project Goal @@ -17,7 +22,9 @@ proxying hosts with SSL termination and it had to be so easy that a monkey could While there might be advanced options they are optional and the project should be as simple as possible so that the barrier for entry here is low. -Buy Me A Coffee +## Raspberry Pi Install +See dock/Raspberry Pi-Install.md and doc/rpi-example for installation instructions. +It has been tested successfully on Raspberry Pi 3 model B. I have not tested this on anything else yet, but I plan on putting this on my Raspberry Pi 2 model B. ## Features diff --git a/doc/Raspberry Pi-INSTALL.md b/doc/Raspberry Pi-INSTALL.md new file mode 100644 index 00000000..eba4d5a6 --- /dev/null +++ b/doc/Raspberry Pi-INSTALL.md @@ -0,0 +1,157 @@ +### This sets up a Raspberry Pi as an all in one PiHole DNS Server with Reverse Proxy capability. +### It is intended for use internally on the LAN only - not to be exposed directly to the internet! + +## Installation and Configuration + +If you just want to get up and running in the quickest time possible, grab all the files in +the [doc/example/](https://github.com/jeff89179/nginx-proxy-manager/tree/master/doc/rpi-example) +folder and run: + +```bash +docker-compose up -d +``` + +### Configuration File + +**The configuration file needs to be provided by you!** + +Don't worry, this is easy to do. + +The app requires a configuration file to let it know what database you're using. + +Here's an example configuration for `mysql` (or mariadb) that is compatible with the docker-compose example below: + +```json +{ + "database": { + "engine": "mysql", + "host": "db", + "name": "npm", + "user": "npm", + "password": "npm", + "port": 3306 + } +} +``` + +Once you've created your configuration file it's easy to mount it in the docker container. + +**Note:** After the first run of the application, the config file will be altered to include generated encryption keys unique to your installation. These keys +affect the login and session management of the application. If these keys change for any reason, all users will be logged out. + + +### Database + +This app doesn't come with a database, you have to provide one yourself. Currently only `mysql/mariadb` is supported for the minimum versions: + +- MySQL v5.7.8+ +- MariaDB v10.2.7+ + +It's easy to use another docker container for your database also and link it as part of the docker stack, so that's what the following examples +are going to use. + +You'll have to create the proper users for the DB and grant them access. Change localhost to the IP your container uses. + +``` +CREATE USER 'npm'@'nginx-proxy-manager_app_1.nginx-proxy-manager_default' IDENTIFIED BY 'npm'; +GRANT ALL PRIVILEGES ON npm.* TO 'npm'@'nginx-proxy-manager_app_1.nginx-proxy-manager_default'; +CREATE USER 'npm'@'localhost' IDENTIFIED BY 'npm'; +GRANT ALL PRIVILEGES ON npm.* TO 'npm'@'localhost'; +``` + +### Running the App + +Via `docker-compose`: + +```yml +version: "3" +services: + app: + image: jc21/nginx-proxy-manager:latest + restart: always + ports: + # Public HTTP Port: + - 80:80 + # Public HTTPS Port: + - 443:443 + # Admin Web Port: + - 81:81 + volumes: + # Make sure this config.json file exists as per instructions above: + - ./config.json:/app/config/production.json + - ./data:/data + - ./letsencrypt:/etc/letsencrypt + depends_on: + - db + db: + image: yobasystems/alpine-mariadb:latest + restart: always + environment: + MYSQL_ROOT_PASSWORD: "npm" + MYSQL_DATABASE: "npm" + MYSQL_USER: "npm" + MYSQL_PASSWORD: "password" + volumes: + - ./data/mysql:/var/lib/mysql +``` + +Then: + +```bash +docker-compose up -d +``` + + +### Running on Raspberry PI / ARM devices + +There are docker images for all versions of the Rasberry Pi with the exception of the really old `armv6l` versions. + +The `latest` docker image is a manifest of all the different architecture docker builds supported, so this means +you don't have to worry about doing anything special and you can follow the common instructions above. + +Check out the [dockerhub tags](https://cloud.docker.com/repository/registry-1.docker.io/jc21/nginx-proxy-manager/tags) +for a list of supported architectures and if you want one that doesn't exist, +[create a feature request](https://github.com/jc21/nginx-proxy-manager/issues/new?assignees=&labels=enhancement&template=feature_request.md&title=). + +Also, if you don't know how to already, follow [this guide to install docker and docker-compose](https://manre-universe.net/how-to-run-docker-and-docker-compose-on-raspbian/) +on Raspbian. + + +### Initial Run + +After the app is running for the first time, the following will happen: + +- The database will initialize with table structures +- GPG keys will be generated and saved in the configuration file +- A default admin user will be created + +This process can take a couple of minutes depending on your machine. + + +### Default Administrator User + +``` +Email: admin@example.com +Password: changeme +``` + +Immediately after logging in with this default user you will be asked to modify your details and change your password. + + +### Advanced Options + +#### X-FRAME-OPTIONS Header + +You can configure the [`X-FRAME-OPTIONS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options) header +value by specifying it as a Docker environment variable. The default if not specified is `deny`. + +```yml + ... + environment: + X_FRAME_OPTIONS: "sameorigin" + ... +``` + +``` +... -e "X_FRAME_OPTIONS=sameorigin" ... +``` diff --git a/doc/rpi-example/config.json b/doc/rpi-example/config.json new file mode 100644 index 00000000..64ab577c --- /dev/null +++ b/doc/rpi-example/config.json @@ -0,0 +1,10 @@ +{ + "database": { + "engine": "mysql", + "host": "db", + "name": "npm", + "user": "npm", + "password": "npm", + "port": 3306 + } +} diff --git a/doc/rpi-example/docker-compose.yml b/doc/rpi-example/docker-compose.yml new file mode 100644 index 00000000..7fd4a72a --- /dev/null +++ b/doc/rpi-example/docker-compose.yml @@ -0,0 +1,29 @@ +version: "3" +services: + app: + image: jc21/nginx-proxy-manager:latest + restart: always + ports: + # Public HTTP Port: + - 80:80 + # Public HTTPS Port: + - 443:443 + # Admin Web Port: + - 81:81 + volumes: + # Make sure this config.json file exists as per instructions above: + - ./config.json:/app/config/production.json + - ./data:/data + - ./letsencrypt:/etc/letsencrypt + depends_on: + - db + db: + image: yobasystems/alpine-mariadb:latest + restart: always + environment: + MYSQL_ROOT_PASSWORD: "npm" + MYSQL_DATABASE: "npm" + MYSQL_USER: "npm" + MYSQL_PASSWORD: "password" + volumes: + - ./data/mysql:/var/lib/mysql