What Belongs in a Security Note for a Self-Hosted Service?
From the earlier reference collection. Read the current software blog.
Help operators understand network exposure, secrets, updates, and recovery responsibilities before deploying a service.
Map the exposed interfaces
A security note should begin with what the service listens on and which interfaces an operator may expose. Name the web interface, API, administrative endpoint, database port, or other network listener that the deployment actually uses. Distinguish a service bound only to a local interface from one reachable on a public address. If a reverse proxy is expected, explain which component terminates external connections and which internal ports should remain private.
Give a deployment example in words or a diagram: users reach the proxy over HTTPS, while the application port is reachable only within the host or private network. Do not imply that this arrangement is automatically enforced if the software does not configure it. Tell operators to confirm the actual firewall and container mappings in their environment.
Explain credential handling
List the credentials the service needs and where it reads them from. If configuration can contain passwords, API tokens, or signing keys, explain that example values are placeholders and that real values must be kept out of public repositories and logs. Mention how credentials can be rotated and what effect rotation has on active sessions or integrations, if known.
A useful note identifies which account has administrative privileges and recommends limiting access to it. Avoid repeating secrets in troubleshooting output. If a token is displayed only once or cannot be recovered, say so and describe the operator's recovery path. Do not claim encryption at rest or secure secret storage unless the deployment actually provides and documents it.
Set update expectations
Self-hosting transfers update work to the operator. Explain how to learn that a release is available, which upgrade procedure applies, and whether a database or configuration migration may be required. Describe the project's support window or update policy only if one exists. Provide a concise pre-upgrade routine: review the release notes, preserve a recoverable backup, and check that the new version supports the current configuration.
For example, if an upgrade changes a configuration key, identify the version where the old key stops working and the replacement. If there is no automatic migration, state that plainly. Readers need to know whether an upgrade can be rolled back and what data may be altered. Avoid suggesting that updating alone eliminates every vulnerability.
Plan recovery before failure
Describe what data and configuration must be backed up, where those files or databases are located, and whether a backup is consistent while the service is running. Explain restoration at a useful level: which version can read the backup, how to test a restore, and whether restoring also requires credentials or encryption keys. A backup that has never been restored is only an assumption about recoverability.
Finish with a responsibility boundary. The project can document the service's behavior and provide updates; the operator controls network exposure, host security, credential storage, update timing, and backup retention. Make that boundary concrete through the deployment steps and link the relevant configuration reference.