No description
  • Go 57.6%
  • TypeScript 25.5%
  • SCSS 7%
  • HTML 4.2%
  • JavaScript 4%
  • Other 1.7%
Find a file
Jonas Leder deb4d44818
All checks were successful
ci / frontend-vulnerabilities (push) Successful in 13s
ci / frontend-tests (push) Successful in 47s
ci / backend-vulnerabilities (push) Successful in 1m33s
ci / backend-integration-tests (push) Successful in 1m13s
ci / backend-security-lint (push) Successful in 2m53s
ci / frontend-e2e-tests (push) Successful in 3m31s
ci / build (push) Successful in 1m49s
ci / frontend-docker (push) Successful in 0s
ci / build-2 (push) Successful in 2m33s
ci / build-1 (push) Successful in 2m12s
ci / backend-docker (push) Successful in 0s
ci / combined-docker (push) Successful in 0s
ci / chart (push) Successful in 0s
ci / build-3 (push) Successful in 36s
Make vulnerability scans non-blocking per step
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-18 10:36:13 +01:00
.forgejo/workflows Make vulnerability scans non-blocking per step 2026-11-18 10:36:13 +01:00
.vscode fix probes 2025-08-23 18:56:06 +02:00
backend Update module github.com/getsentry/sentry-go to v0.50.0 2026-10-26 21:08:31 +00:00
container add sentry integration 2026-10-06 23:21:13 +02:00
frontend Merge branch 'renovate/sentry-javascript-monorepo' into 'master' 2026-11-14 12:36:40 +01:00
helm Port CI to Forgejo Actions 2026-11-18 10:20:32 +01:00
.dockerignore optimize ignore lists 2025-06-16 10:56:46 +02:00
.gitignore add full integration tests 2026-10-24 16:15:21 +02:00
Dockerfile Update golang Docker tag to v1.27.4 2026-11-13 09:35:08 +00:00
Dockerfile.backend Update golang Docker tag to v1.27.4 2026-11-13 09:35:08 +00:00
Dockerfile.frontend Update cgr.dev/chainguard/nginx Docker digest to 9708b6c 2026-11-17 21:15:24 +00:00
README.md Port CI to Forgejo Actions 2026-11-18 10:20:32 +01:00
renovate.json Migrate config renovate.json 2024-11-10 22:06:34 +01:00

Privatenote

Share encrypted, self-destructing messages. Messages are encrypted in the browser before they are sent, so the server stores only ciphertext.

This repository contains:

  • backend/: Go API server (Gin, GORM). Stores messages and, when configured, serves the frontend.
  • frontend/: TypeScript/SCSS app, built with Symfony Encore.
  • Dockerfile: combined image (API + frontend). Recommended for Docker.
  • Dockerfile.backend / Dockerfile.frontend: separate API and static frontend images, for setups with your own reverse proxy.
  • helm/: Helm chart for Kubernetes.

Contents

Quick start with Docker

The combined Dockerfile builds one image that serves the API and the frontend on port 8080.

Build the image:

docker build -f Dockerfile -t privatenote .

Optional build arguments for the footer version info (passed by CI (Forgejo Actions run number, ref name, short SHA), not required): CI_PIPELINE_ID, CI_COMMIT_REF_NAME, CI_COMMIT_SHORT_SHA.

Run it with SQLite (the default database), storing the database in ./data:

mkdir -p ./data
# the container runs as UID 1000, the directory must be writable for it
sudo chown 1000:1000 ./data

docker run -d --name privatenote \
  -p 8080:8080 \
  -e DB_NAME=/data/privatenote.db \
  -v "$PWD/data:/data" \
  privatenote

Open http://localhost:8080.

Notes:

  • The image is based on scratch and runs as UID 1000. It has no shell and no /data directory, so mount a directory that UID 1000 can write to.
  • Without DB_NAME=/data/... the SQLite file is written to /database.db inside the container and is lost when the container is removed.
  • Without SHARED_SECRET messages are only encrypted in the browser. See Shared secret before you set it.

Docker with an external database

Set DB_DRIVER to mysql or postgres and pass the connection settings as environment variables. No volume is needed.

PostgreSQL

docker run -d --name privatenote \
  -p 8080:8080 \
  -e DB_DRIVER=postgres \
  -e DB_HOST=db.example.internal \
  -e DB_PORT=5432 \
  -e DB_NAME=privatenote \
  -e DB_USER=privatenote \
  -e DB_PASSWORD='change-me' \
  -e DB_SSLMODE=require \
  privatenote

MySQL / MariaDB

docker run -d --name privatenote \
  -p 8080:8080 \
  -e DB_DRIVER=mysql \
  -e DB_HOST=db.example.internal \
  -e DB_PORT=3306 \
  -e DB_NAME=privatenote \
  -e DB_USER=privatenote \
  -e DB_PASSWORD='change-me' \
  privatenote

The database and user have to exist already. Privatenote creates its table (message) at startup, see Database.

Docker Compose example

services:
  privatenote:
    image: privatenote
    ports:
      - "8080:8080"
    environment:
      DB_DRIVER: postgres
      DB_HOST: db
      DB_PORT: "5432"
      DB_NAME: privatenote
      DB_USER: privatenote
      DB_PASSWORD: change-me
      DB_SSLMODE: disable
      # SHARED_SECRET: "..."   # see the Shared secret section before setting it
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: privatenote
      POSTGRES_USER: privatenote
      POSTGRES_PASSWORD: change-me
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U privatenote -d privatenote"]
      interval: 5s
      retries: 10
    restart: unless-stopped

volumes:
  pgdata:

Replace change-me with real passwords. DB_SSLMODE: disable is only suitable for the internal Compose network.

Separate images

Dockerfile.backend builds the API only. It does not serve the frontend (SERVE_STATIC is off), so the frontend must come from Dockerfile.frontend (nginx, port 8080) or another web server. Your reverse proxy must send /api/ to the backend and everything else to the frontend. The backend needs a reachable TRUSTED_PROXIES setting if the proxy is not on a private network, see Configuration reference.

Helm

The chart in helm/ deploys a backend and a frontend Deployment, their Services, an optional Ingress, and optionally a MariaDB database (Bitnami subchart).

Requirements

  • Kubernetes and Helm 3
  • Access to the images (forgejo.jonasled.dev/jonasled/privatenote-symfony/backend and .../frontend). The image tag defaults to the chart appVersion, override it with image.tag.

Install with the bundled MariaDB

helm dependency build helm

helm install privatenote ./helm \
  --namespace privatenote --create-namespace \
  --set sharedSecret.value="$(openssl rand -base64 32)" \
  --set ingress.enabled=true \
  --set ingress.className=nginx \
  --set 'ingress.hosts[0].host=notes.example.com' \
  --set 'ingress.tls[0].secretName=notes-example-com-tls' \
  --set 'ingress.tls[0].hosts[0]=notes.example.com'

helm dependency build helm is required once, and again after changing the chart dependencies. It downloads the MariaDB subchart into helm/charts/, which is git-ignored. It is required even when mariadb.enabled=false, because the templates use helpers from that subchart.

Without an Ingress, reach the frontend and API through a port-forward or a Service:

kubectl -n privatenote port-forward svc/privatenote-frontend 8080:80

Routing note: when the Ingress is enabled, / goes to the frontend and /api goes to the backend. Without an Ingress there is no proxy for /api, so use an Ingress or your own reverse proxy in front of both services.

Install with an external MariaDB / MySQL

kubectl -n privatenote create secret generic privatenote-db \
  --from-literal=mariadb-password='change-me'

helm install privatenote ./helm \
  --namespace privatenote \
  --set mariadb.enabled=false \
  --set mariadb.external.host=db.example.internal \
  --set mariadb.auth.database=privatenote \
  --set mariadb.auth.username=privatenote \
  --set mariadb.auth.existingSecret=privatenote-db \
  --set sharedSecret.value="$(openssl rand -base64 32)"

The Secret must contain the key mariadb-password. mariadb.auth.existingSecret is required here, otherwise the backend looks for a Secret of the bundled database.

The chart always sets DB_DRIVER=mysql. PostgreSQL cannot be selected through the chart yet, use the Docker setup or your own manifests for it.

Upgrade and uninstall

helm upgrade privatenote ./helm --namespace privatenote --reuse-values
helm uninstall privatenote --namespace privatenote

helm uninstall does not delete the PersistentVolumeClaim of the bundled database, so the data survives a reinstall. Keep your shared secret too, see Shared secret.

Chart values

Set values with --set or a values file (-f my-values.yaml). Defaults are in helm/values.yaml.

Value Default Description
replicaCountBackend 1 Backend replicas (ignored when autoscaling.enabled).
replicaCountFrontend 1 Frontend replicas (ignored when autoscaling.enabled).
image.repositoryBackend forgejo.jonasled.dev/jonasled/privatenote-symfony/backend Backend image.
image.repositoryFrontend forgejo.jonasled.dev/jonasled/privatenote-symfony/frontend Frontend image.
image.pullPolicy IfNotPresent Image pull policy.
image.tag "" (chart appVersion) Image tag for both images.
imagePullSecrets [] Pull secrets for private registries.
nameOverride, fullnameOverride "" Naming of the resources.
serviceAccount.create true Create a ServiceAccount.
serviceAccount.name, serviceAccount.annotations "", {} Name and annotations of the ServiceAccount.
podAnnotations {} Extra pod annotations.
podSecurityContext non-root, RuntimeDefault seccomp Pod security context.
securityContext no privilege escalation, read-only root filesystem, all capabilities dropped Container security context.
service.type ClusterIP Service type for both Services.
service.port 80 Service port (container port is 8080).
ingress.enabled false Create an Ingress.
ingress.className "" Ingress class, e.g. nginx.
ingress.annotations {} Ingress annotations.
ingress.hosts chart-example.local, path / Hosts and paths. Each path is also routed to <path>api for the backend, so keep /.
ingress.tls [] TLS entries (secretName, hosts).
resources {} Container resources for both Deployments.
autoscaling.enabled false Create an HPA. The template uses autoscaling/v2beta1, which current Kubernetes versions no longer serve, so it does not work there yet.
autoscaling.minReplicas, maxReplicas 1, 100 HPA bounds.
autoscaling.targetCPUUtilizationPercentage 80 HPA CPU target.
nodeSelector, tolerations, affinity empty Scheduling.
backend.trustedProxies "" Comma separated CIDRs of proxies allowed to set X-Forwarded-For. Empty uses private networks.
backend.rateLimit 60 Requests per minute and client IP to the message API, 0 disables it.
backend.rateLimitBurst 20 Burst size of the rate limit.
backend.maxMessageSize 1048576 Maximum body size of a new message in bytes.
sentry.enabled true Send errors to Sentry / GlitchTip.
sentry.dsn project DSN of the maintainers Set your own DSN or set sentry.enabled=false.
sentry.frontend true Also report browser errors (through the backend).
sentry.securityEndpoint maintainers' endpoint CSP violation reports endpoint. Empty disables them.
sentry.environment production Environment name in Sentry.
sentry.tracesSampleRate 0.1 Share of requests traced (0 to 1).
sharedSecret.value "" Inline shared secret, the chart creates a Secret. See Shared secret.
sharedSecret.existingSecret "" Existing Secret with the shared secret (takes precedence over value).
sharedSecret.existingSecretKey shared-secret Key in the existing Secret.
mariadb.enabled true Deploy the bundled MariaDB (Bitnami subchart, version 28.1.1).
mariadb.external.host mariadb Host of an external database when mariadb.enabled=false.
mariadb.auth.database privatenote Database name.
mariadb.auth.username privatenote Database user.
mariadb.auth.existingSecret "" Secret with the key mariadb-password. Required for an external database.
mariadb.secondary.replicaCount 0 Read replicas of the bundled MariaDB.

The rest of the MariaDB subchart values (storage, passwords, resources) are passed through the mariadb key, see the Bitnami MariaDB chart.

Configuration reference

The backend reads these environment variables. The Helm chart sets most of them from the values above, Docker users pass them with -e.

Database connection

Variable Default Description
DB_DRIVER sqlite sqlite, mysql or postgres.
DB_NAME ./database.db (sqlite) SQLite file path, or database name for MySQL / PostgreSQL. Required for MySQL and PostgreSQL.
DB_HOST Database host. Required for MySQL and PostgreSQL.
DB_PORT 3306 (MySQL), 5432 (PostgreSQL) Database port.
DB_USER Database user. Required for MySQL and PostgreSQL.
DB_PASSWORD Database password. Required for MySQL and PostgreSQL.
DB_SSLMODE disable PostgreSQL SSL mode: disable, require, verify-ca, verify-full. Use require or stricter outside a private network.
EXECUTE_MIGRATIONS true Create or migrate the table at startup. Set false to manage the schema yourself.

The MySQL connection uses utf8mb4, parseTime=True and the server's local time zone. The PostgreSQL connection uses TimeZone=UTC.

Server

Variable Default Description
PORT 8080 Listen port.
GIN_MODE release (in the image) Gin mode. Keep release.
SERVE_STATIC false (true in the combined image) Serve the frontend from STATIC_DIR.
STATIC_DIR ./target Directory with the built frontend (index.html, decrypt.html, ...).
TRUSTED_PROXIES private networks and loopback Comma separated CIDRs of proxies whose X-Forwarded-For header is trusted. Set this if your proxy or CDN is outside private networks, otherwise all clients share one rate limit.
MAX_MESSAGE_SIZE 1048576 Maximum body size of a new message in bytes. Must be positive.
RATE_LIMIT 60 Requests per minute and client IP to the message API. 0 disables the limit.
RATE_LIMIT_BURST 20 Burst size, at least 1.

Health endpoints: GET /api/health (readiness) and GET /api/health/liveness. API documentation is served at /api/doc/index.html.

Encryption

Variable Default Description
SHARED_SECRET empty Enables a second, server side encryption layer for stored messages. See Shared secret.

Error reporting

Variable Default Description
SENTRY_DSN empty Sentry / GlitchTip DSN. Empty disables error reporting. Events never contain message links, passwords or client data.
SENTRY_ENVIRONMENT production Environment name.
SENTRY_RELEASE empty Release name. The Helm chart sets it to the image tag.
SENTRY_TRACES_SAMPLE_RATE 0 Share of requests traced with their database queries (0 to 1).
SENTRY_FRONTEND true Forward browser errors through /api/sentry.
SENTRY_SECURITY_ENDPOINT empty Endpoint for CSP violation reports, forwarded through /api/csp-report. Empty disables them.

Database

  • Privatenote has one table, message. It is created by EXECUTE_MIGRATIONS at startup (AutoMigrate). Migrations only add tables and columns, they do not drop anything.
  • Use a dedicated database and user with rights on that database.
  • Back up the database regularly. Messages are encrypted, but losing the database loses all messages.
  • SQLite is a single file, use MySQL or PostgreSQL when you run more than one backend replica.
  • Expired messages are deleted when the API is called, and they are never returned, even before they are deleted.

Shared secret

SHARED_SECRET (sharedSecret.value in Helm) adds server side encryption on top of the browser encryption. The key is derived from the secret with HKDF-SHA256.

  • Generate a long random value, for example openssl rand -base64 32.
  • Do not change or remove it once messages are stored. Messages written with the old secret cannot be decrypted by the server anymore, so they can no longer be read.
  • Keep a copy of the value in a password manager. Losing it has the same effect as changing it.
  • Without a shared secret the server stores only the browser encrypted messages. Setting it later only affects new messages, existing ones stay as they are.

Development

Requirements: Go (see backend/go.mod for the version), Node.js 24 and Yarn (see the packageManager field in frontend/package.json).

Backend:

cd backend
go run .                    # uses sqlite at ./database.db, port 8080
go test ./...               # integration tests, using a temporary sqlite database
go vet ./...

Frontend:

cd frontend
yarn install
yarn build                  # production build in target/
yarn dev                    # development build with Encore
yarn test                   # unit tests (vitest)
yarn test:e2e               # Playwright end to end tests

To run the full stack locally, build the frontend, then start the backend with SERVE_STATIC=true STATIC_DIR=../frontend/target (adjust the path to the frontend build). The API docs are generated into backend/docs/.

Helm chart development

helm dependency build helm
helm lint helm
helm template privatenote helm