shaspen/netdot repository overview

⁠netdot-docker

Run Netdot⁠ (the Network Documentation Tool) in Docker: a single centos:7.9.2009-based image with Apache + mod_perl and a MySQL-compatible database, fronted by an nginx reverse proxy that terminates TLS. The install follows DigitalOcean's How To Document Your Network with Netdot on CentOS 7 tutorial.

• One app image — Netdot, Apache (HTTP :80 only) and the database in the same container, built with a multi-stage Dockerfile (~757 MB).
• nginx in front — TLS termination, HTTP→HTTPS redirect, security headers.
• Database import — load *.sql / *.sql.gz dumps from an existing Netdot installation into the running container.
• End-to-end check — verify.sh logs in through the proxy to prove the whole stack works.

 browser ──443/80──▶ nginx (TLS) ──HTTP──▶ netdot container
                                            ├─ Apache + mod_perl (Netdot)
                                            └─ MariaDB 5.5 (socket only)

⁠Requirements

• Docker with the Compose plugin (docker compose) and BuildKit
• openssl and curl (certificate generation and verification)
• Network access to mirrors.aliyun.com (CentOS vault + EPEL archive), github.com (Netdisco MIBs, DNSSEC-Tools) and cpan.org at build time. The CentOS 7 mirrors can be changed with --build-arg MIRROR=....

⁠Quick start

git clone <this-repo-url> netdot-docker && cd netdot-docker
git clone https://github.com/cvicente/Netdot.git Netdot   # the app source (build context)

./gen-certs.sh                    # self-signed cert in ./certs (or supply your own)
docker compose up -d --build      # first build takes a while
./verify.sh                       # scripted login through nginx -> PASS

Open https://localhost/netdot/⁠ and sign in with admin / admin. Change that password immediately, along with the database passwords below.

If ports 80/443 are taken on the host:

HTTP_PORT=8081 HTTPS_PORT=8443 docker compose up -d --build
BASE_URL=https://localhost:8443/netdot HTTP_URL=http://localhost:8081 ./verify.sh

⁠Configuration

Environment variables (set them in the shell or an .env file next to docker-compose.yml):

Avoid ' characters in passwords: they are written into Netdot's Site.conf and SQL statements unescaped.

⁠TLS certificates

./gen-certs.sh creates a self-signed certificate (CN localhost). For a real certificate put fullchain.pem and privkey.pem in certs/ (or point CERT_DIR at them). Apache inside the image serves plain HTTP only; there is no mod_ssl, and only nginx publishes ports.

⁠Persistent data

The database lives in the netdot-db volume (/var/lib/mysql). It is initialised on first start (make installdb) and reused afterwards.

⁠Importing an existing database

Migrate a database from a working Netdot system into the running container. Supported files: *.sql and *.sql.gz.

1. On the source system, create a dump:

   mysqldump --single-transaction netdot | gzip > netdot.sql.gz
   

   Copy

2. Import it into the running container:

   docker cp netdot.sql.gz netdot-docker-netdot-1:/tmp/
   docker exec netdot-docker-netdot-1 \
     /docker-entrypoint.sh import --replace --upgrade /tmp/netdot.sql.gz
   

   Copy

   (Use docker compose ps for the actual container name.)

Behaviour:

• An import replaces the Netdot database. If it already contains tables the command refuses to run without --replace; with --replace it first writes pre-import-<timestamp>.sql.gz to /var/lib/mysql/ as a backup.
• Files are validated before anything is dropped (.sql/.sql.gz only, gzip integrity checked); a load error aborts with the MySQL message.
• The application user's privileges are re-applied after every import (dumps do not carry MySQL users).
• --upgrade runs Netdot's make upgrade for dumps from older Netdot versions; a dump already at the current schema is left alone. Back up first — see Netdot's doc/UPGRADE.
• First start: *.sql / *.sql.gz in /docker-entrypoint-initdb.d/ (mount a directory there) or the file named by DB_IMPORT_FILE are imported instead of running make installdb, once, when the database does not exist.

Limitations: the server is MariaDB 5.5, so dumps from MySQL 8.0 that use utf8mb4_0900_* collations or other 8.0-only syntax will not load (MySQL 5.x and MariaDB dumps are fine). The dump's database name must match DB_DATABASE.

⁠Image notes

• Multi-stage build: a builder stage compiles/installs all Perl dependencies; the runtime stage carries only runtime packages plus /usr/local.
• SNMP MIBs are limited to rfc net-snmp cisco; add vendors with --build-arg MIB_DIRS="rfc net-snmp cisco juniper".
• Netdot's cron file is installed but crond is not run, and snmpd is not started. Run scheduled Netdot jobs from the host or an extra container if you need them.
• Apache trusts X-Forwarded-For from private networks (mod_remoteip), so Netdot sees client addresses behind the proxy.

⁠Testing

./verify.sh                  # login through nginx (wrong password rejected,
                             # admin/admin accepted, HTTP -> HTTPS 301)
./tests/test-import.sh       # import feature, against real containers
                             # (IMAGE=netdot:local PORT=8082 by default)

⁠Repository layout

⁠Security notes

• Default credentials (admin/admin, rootpass, netdot_pass) are for getting started only — change them before exposing the service.
• The database listens on its Unix socket only (skip-networking); it is not reachable over TCP, even from other containers.
• CentOS 7 is end-of-life and receives no security updates; keep the service behind a firewall or VPN and do not expose it to untrusted networks.

⁠License

Netdot is licensed under the GPL. This project is licensed under the MIT License.

⁠Author