Server configuration

nexmapd is configured through environment variables, most of which also have a command line flag. Each setting is taken from the first source that has it: flag, then environment variable, then the built-in default. There is no configuration file.

The container image sets some variables differently from the built-in defaults; both are listed below.

Reference

Network

Without NEXMAP_PUBLIC_URL, invitation links are built from the address the inviter’s browser used, taking the scheme from the proxy’s X-Forwarded-Proto header. That is right behind a typical proxy, but set the variable if Nexmap is reachable under more than one name, or if links come out with http://. The server does not start if the value is not an absolute http or https URL.

NEXMAP_TRUSTED_PROXIES decides whose word Nexmap takes for a client’s address, which the login limits count by. The default (127.0.0.0/8, ::1, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7) fits a proxy on the same host or container network. Narrow it to your proxy’s address if other machines on those networks can reach nexmapd directly. The server does not start if an entry is not an IP address or CIDR range. See Security.

nexmapd serves plain HTTP. Put it behind a reverse proxy that terminates TLS; see Security.

Database

SQLite suits small installations: one file, no separate server, run in WAL mode with a single connection. PostgreSQL suits larger ones; nexmapd opens up to 25 connections. Either way, the database is created or migrated automatically at startup, and the server refuses to start if it cannot reach it.

Encryption

The server does not start without it.

First administrator

These are only read when the database has no users yet, i.e. on the very first start. See Security.

Sessions and passwords

Each password hash records its own iteration count, so changing NEXMAP_PBKDF2_ITERATIONS applies to passwords set from then on; existing passwords keep working.

Attachments

The presets are images (.png, .jpg, .jpeg, .gif, .webp), logs (.txt, .log, .json, .xml, .csv, .md, .yaml, .yml) and documents (.pdf). For example, NEXMAP_ALLOWED_UPLOAD_TYPES=images,logs,zip allows those presets plus .zip files.

Besides the extension, the server checks the file content: a file named .png must really be an image, and a text extension rejects content recognised as an archive, PDF or media file. This stops mislabelled uploads but is not a malware scanner. Attachments are always served as downloads, never rendered or executed by the browser.

Mail

Nexmap can send two kinds of email, and no others: invitations and password reset links. Mail is optional. Without it, invitations are links that the inviter passes on, and an administrator sets a new password for someone who forgot theirs.

The mail settings have no command line flags: they include secrets, and a process’s command line is visible to other users of the machine. The server does not start if the mail configuration is incomplete or invalid, or if a transport is set without NEXMAP_PUBLIC_URL. The links in emails are always built from NEXMAP_PUBLIC_URL, never from the request, so nobody can make Nexmap send a reset link that points to another site.

Services that are not in the list can be used through their SMTP relay, such as Amazon SES, Postmark or Brevo. Scaleway, MailPace and Lettermint can also be reached by SMTP, if you prefer that.

Examples:

# An SMTP relay with STARTTLS on port 587
NEXMAP_MAIL_TRANSPORT=smtp
NEXMAP_MAIL_FROM='Nexmap <nexmap@example.com>'
NEXMAP_SMTP_HOST=smtp.example.com
NEXMAP_SMTP_USERNAME=nexmap
NEXMAP_SMTP_PASSWORD='<password>'

# Scaleway Transactional Email through its API
NEXMAP_MAIL_TRANSPORT=scaleway
NEXMAP_MAIL_FROM=nexmap@example.com
NEXMAP_MAIL_API_KEY='<secret key>'
NEXMAP_SCALEWAY_PROJECT_ID='<project id>'

At startup the log says mail enabled with the transport, or mail disabled. Each email is logged as mail sent or mail not sent with its purpose (invitation or password_reset), never with the address or the link. See Security for what the emails contain and how they are limited.

Logging

Logs are JSON, one entry per line.

Development

Value formats

• Boolean variables (NEXMAP_COOKIE_SECURE, NEXMAP_DEV_MODE) are true for true or 1; any other value means false.
• An invalid duration or number (NEXMAP_SESSION_TTL, NEXMAP_PBKDF2_ITERATIONS, NEXMAP_MAX_UPLOAD_BYTES) is ignored and the default is used, without a warning. Check the values carefully.
• An unknown log level or database driver stops the server with an error.
• The mail settings are checked strictly: an invalid number, port or option stops the server with an error.

Health check

nexmapd healthcheck requests /api/v1/health from the server running with the same configuration and exits with 0 if it answers. The container image uses it as its HEALTHCHECK; outside a container, the endpoint can be polled directly.

Minimal production setup

NEXMAP_ENCRYPTION_KEY='[{"id":"2026-01","key":"<base64 key>"}]'
NEXMAP_ADMIN_USER=jdoe
NEXMAP_ADMIN_PASSWORD='<long random password>'
# for PostgreSQL instead of SQLite:
NEXMAP_DB_DRIVER=postgres
NEXMAP_DB_DSN='postgres://nexmap:<password>@db:5432/nexmap?sslmode=require'

Behind a TLS-terminating proxy, the remaining defaults are suitable for production.