Skip to content

Getting Started

Jump to bottom
DenAV edited this page Mar 19, 2026 · 2 revisions

Getting Started

Prerequisites

  • Ansible >= 2.12 (install guide)
  • Python >= 3.9 with pip
  • Docker & Docker Compose on the target host
  • A running Nginx Proxy Manager instance (v2.11.3+)

Note: Ansible, Python, and pip run on your local machine (the control node). The target host only needs Docker.

Installation

1. Clone the repository

git clone https://github.com/DenAV/nginx-proxy-manager-ansible.git /opt/npm
cd /opt/npm

2. Install Python dependencies (local machine)

python3 -m venv .venv
source .venv/bin/activate    # Linux/macOS
# .venv\Scripts\activate     # Windows (PowerShell)

pip install -r requirements-dev.txt

Note: Modern Linux distributions (Ubuntu 24.04+) require a virtual environment for pip. On Windows with a system-wide Python install, pip install works directly without a venv.

3. Deploy Nginx Proxy Manager (if not running)

On the target host (server with Docker), start NPM using the project's docker-compose file:

cd /opt/npm/docker
# Edit docker-compose_npm.yml — set ports, volumes, etc.
docker compose -f docker-compose_npm.yml up -d

Default NPM ports:

  • 80 — HTTP
  • 443 — HTTPS
  • 81 — Admin API / Web UI

4. Configure API credentials (local machine)

Create an encrypted vault file with your NPM admin credentials:

ansible-vault create roles/npm-management/vars/api_secret.yml

Add the following content:

---
npm_user: admin@example.com
npm_password: changeme

Note: Default NPM credentials are admin@example.com / changeme. Change them after first login.

5. Run the playbook

# With vault password prompt
ansible-playbook pl_npm-management.yml --ask-vault-pass

# With vault password file
ansible-playbook pl_npm-management.yml --vault-password-file .vault-pass

First Run Checklist

  1. NPM is running and accessible at http://<your-ip>:81
  2. You've changed the default NPM admin password
  3. api_secret.yml is encrypted with Ansible Vault
  4. .gitignore contains **/api_secret.yml
  5. npm_api_url points to your NPM instance (see Configuration)

Next Steps

Clone this wiki locally