- Go 57.6%
- TypeScript 25.5%
- SCSS 7%
- HTML 4.2%
- JavaScript 4%
- Other 1.7%
|
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
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> |
||
|---|---|---|
| .forgejo/workflows | ||
| .vscode | ||
| backend | ||
| container | ||
| frontend | ||
| helm | ||
| .dockerignore | ||
| .gitignore | ||
| Dockerfile | ||
| Dockerfile.backend | ||
| Dockerfile.frontend | ||
| README.md | ||
| renovate.json | ||
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
- Docker with an external database
- Helm
- Configuration reference
- Database
- Shared secret
- Development
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
scratchand runs as UID 1000. It has no shell and no/datadirectory, so mount a directory that UID 1000 can write to. - Without
DB_NAME=/data/...the SQLite file is written to/database.dbinside the container and is lost when the container is removed. - Without
SHARED_SECRETmessages 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/backendand.../frontend). The image tag defaults to the chartappVersion, override it withimage.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 byEXECUTE_MIGRATIONSat 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