Home

Awesome

NPMplus

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 TLS, without having to know too much about Nginx or Certbot.

Note: NO armv7, route53 and aws cloudfront ip ranges support. <br> Note: Other Databases like MariaDB may work, but are unsupported. <br> Note: watchtower does NOT update NPMplus, you need to do it yourself (it will only pull the image, but not update the container itself). <br> Note: access.log/stream.log, logrotate and goaccess are NOT enabled by default bceuase of GDPR, you can enable them in the compose.yaml. <br>

Note: add net.ipv4.ip_unprivileged_port_start=0 at the end of /etc/sysctl.conf to support PUID/PGID in network mode host. <br> Note: Don't forget to open Port 80 (tcp) and 443 (tcp AND udp, http3/quic needs udp) in your firewall (because of network mode host, you also need to open this ports in ufw, if you use ufw). <br> Note: If you don't use network mode host, which I don't recommend, don't forget to also expose port 443/udp (http3/quic needs udp), to enable IPv6 in Docker see step 1 and 2 here. <br>

Project Goal

I created this project to fill a personal need to provide users with an easy way to accomplish reverse proxying hosts with TLS termination and it had to be so easy that a monkey could do it. This goal hasn't changed. 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.

Features

List of new features

migration

Quick Setup

  1. Install Docker and Docker Compose (or portainer)
  1. Download this compose.yaml (or use its content as a portainer stack)
  2. adjust TZ and ACME_EMAIL to your values and maybe adjust other env options to your needs.
  3. start NPMplus by running (or deploy your portainer stack)
docker compose up -d
  1. Log in to the Admin UI When your docker container is running, connect to it on port 81 for the admin interface. Sometimes this can take a little bit because of the entropy of keys. You may need to open port 81 in your firewall. You may need to use another IP-Address. https://127.0.0.1:81 Default Admin User:
Email:    admin@example.org
Password: iArhP1j7p1P6TA92FA2FMbbUGYqwcYzxC4AVEe12Wbi94FY9gNN62aKyF1shrvG4NycjjX9KfmDQiwkLZH1ZDR9xMjiG2QmoHXi

Immediately after logging in with this default user you will be asked to modify your details and change your password.

Crowdsec

Note: Using Immich behind NPMplus with enabled appsec causes issues, see here: #1241

  1. Install crowdsec using this compose file: https://github.com/ZoeyVid/NPMplus/blob/develop/compose.crowdsec.yaml and enable LOGROTATE in the NPMplus compose file
  2. open /opt/crowdsec/conf/acquis.d/npmplus.yaml and fill it with:
filenames:
  - /opt/npm/nginx/access.log
labels:
  type: npmplus
---
source: docker
container_name:
 - npmplus
labels:
  type: npmplus
---
source: docker
container_name:
 - npmplus
labels:
  type: modsecurity
---
listen_addr: 0.0.0.0:7422
appsec_config: crowdsecurity/appsec-default
name: appsec
source: appsec
labels:
  type: appsec
  1. make sure to use network_mode: host in your compose file
  2. run docker exec crowdsec cscli bouncers add npmplus -o raw and save the output
  3. open /opt/npm/etc/crowdsec/crowdsec.conf
  4. set ENABLED to true
  5. use the output of step 5 as API_KEY
  6. save the file
  7. set LOGROTATE to true in your compose.yaml
  8. redeploy the compose.yaml

coreruleset plugins

  1. Download the plugin (all files inside the plugins folder of the git repo), most time: <plugin-name>-before.conf, <plugin-name>-config.conf and <plugin-name>-after.conf and sometimes <plugin-name>.data and/or <plugin-name>.lua or somilar files
  2. put them into the /opt/npm/etc/modsecurity/crs-plugins folder
  3. maybe open the /opt/npm/etc/modsecurity/crs-plugins/<plugin-name>-config.conf and configure the plugin

Use as webserver

  1. Create a new Proxy Host
  2. Set Scheme to https, Forward Hostname / IP to 0.0.0.0, Forward Port to 1 and enable Websockets Support (you can also use other values, since these get fully ignored)
  3. Maybe set an Access List
  4. Make your TLS Settings

a) Custom Nginx Configuration (advanced tab), which looks the following for file server:

location / {
    include conf.d/include/always.conf;
    alias /var/www/<your-html-site-folder-name>/;
    fancyindex off; # alternative to nginxs "index" option (looks better and has more options)
}

b) Custom Nginx Configuration (advanced tab), which looks the following for file server and php:

location / {
    include conf.d/include/always.conf;
    alias /var/www/<your-html-site-folder-name>/;
    fancyindex off; # alternative to nginxs "index" option (looks better and has more options)

    location ~ [^/]\.php(/|$) {
        fastcgi_pass php82;
        fastcgi_split_path_info ^(.+?\.php)(/.*)$;
        if (!-f $document_root$fastcgi_script_name) {
            return 404;
        }
    }
}

prerun scripts (EXPERT option) - if you don't know what this is, ignore it

run order: entrypoint.sh (prerun scripts) => start.sh => launch.sh <br> if you need to run scripts before NPMplus launches put them under: /opt/npm/etc/prerun/*.sh (please add #!/bin/sh / #!/bin/bash to the top of the script) <br> you need to create this folder yourself - NOTE: I won't help you creating those patches/scripts if you need them you also need to know how to create them

Contributing

All are welcome to create pull requests for this project.

Please report Bugs first to this fork before reporting them to the upstream Repository

Getting Help

  1. Support/Questions
  2. Reddit
  3. Bugs