Overview
Clipora is a self-hosted notes and journal application backed by PostgreSQL. The application container connects to a separately managed database.
Notes, labels, and journal
Clipora keeps organization flexible without making daily capture complicated.
Requirements
A small Linux server is enough for personal and family use. Install the following before starting:
- Docker Engine 24+
- Docker Compose v2
- 1 CPU / 512 MB RAM
- A domain name and reverse proxy are optional for local use, recommended for internet access.
Installation
Clone the repository, prepare the environment file, and start the production container:
git clone <your-clipora-repository-url> clipora
cd clipora
cp .env.example .env
docker compose up -d --buildAfter the health check passes, open http://localhost:3000
Environment variables
Set these values in .env before the first production start. Never commit real secrets to Git.
| Variable | Required | Description |
|---|---|---|
| DATABASE_URL | Yes | PostgreSQL connection URL reachable from the application container |
| NEXTAUTH_URL | Yes | Public application URL, including https:// in production |
| NEXTAUTH_SECRET | Yes | Long random secret used to sign authentication data |
| GOOGLE_CLIENT_ID | No | Optional Google OAuth client ID |
| GOOGLE_CLIENT_SECRET | No | Optional Google OAuth client secret |
| STORAGE_DRIVER | No | Use local (default) or s3 upload storage |
| S3_ENDPOINT | With s3 | S3-compatible API endpoint, including https:// |
| S3_REGION | No | S3 signing region; defaults to us-east-1 |
| S3_BUCKET | No | Private upload bucket; defaults to clipora |
| S3_ACCESS_KEY_ID | With s3 | S3 access key ID |
| S3_SECRET_ACCESS_KEY | With s3 | S3 secret access key |
| S3_FORCE_PATH_STYLE | No | Path-style S3 URLs; defaults to true for self-hosted services |
| HOST_PORT | No | Host port exposed by Docker Compose; defaults to 3000 |
Google OAuth
Google login is optional. Create a Web OAuth client in Google Cloud, set the client ID and secret, then add this authorized redirect URI:
https://your-domain.example/api/auth/callback/googleData and attachment storage
Notes, journal entries, labels, and account data live in PostgreSQL. Uploaded note and journal images and files remain under /app/data, which Docker Compose maps to the clipora-data volume.
volumes:
- clipora-data:/app/dataUpdating Clipora
Back up the data volume, pull the latest code, and rebuild the container. Database migrations run automatically at startup.
git pull
docker compose up -d --build
docker image prune -fBackup
Back up PostgreSQL with your database provider and back up the attachment volume separately. This example writes the attachment volume to an archive in the current directory:
docker run --rm \
-v clipora_clipora-data:/data \
-v "$(pwd)":/backup \
alpine tar czf /backup/clipora-backup.tar.gz -C /data .Production security
Before exposing Clipora to the internet, complete this short security checklist:
- Terminate HTTPS with a trusted reverse proxy such as Caddy, Traefik, or Nginx.
- Use a long random NEXTAUTH_SECRET and keep .env outside version control.
- Schedule encrypted off-server backups and test restoring them.
- Expose only the reverse proxy publicly; restrict PostgreSQL access to trusted networks whenever possible.