Self-Hosting

heaper can be self-hosted, giving you complete control over your data and infrastructure.

Prerequisites

Docker
Domain with SSL/TLS certificate (recommended but not required)

The easiest way to self-host heaper is using Docker: make sure to define paths for the contfig folder as well as the data directories set a password for the postgres server too make sure you save this snippet you customized somewhere as you need it when you update or recreate the container the paths for you to adjust are the ones before the : on each --volume, thumbnails preferrably on an ssd but through the local first nature of heaper this is not required but speeds up initial syncs.

an image that work with an postgres install shipped ENABLE_INTERNAL_POSTGRES will toggle that on bit its still WIP

# run db
docker run -d --rm --name heaper-selfhost-postgres \
-e POSTGRES_USER=heaper \
-e POSTGRES_PASSWORD=YOURPASSWORD \
-e POSTGRES_DB=heaper \
-p "5432:5432" \
--volume /mnt/user/appdata/heaper-selfhost/postgres:/var/lib/postgresql/data \
--network heaper \
ghcr.io/janlunge/heaper-postgres:latest

docker run --rm --name heaper-selfhost -d \
-p 3000:443 \
-p 4499:80 \
-e HOSTNAME=wdata.local \
-e ENABLE_INTERNAL_POSTGRES=false \
-e DB_HOST=heaper-selfhost-postgres:5432 \
-e DB_USER=heaper \
-e DB_PASS=YOURPASSWORD \
-e DB_NAME=heaper \
--volume /mnt/user/appdata/heaper-selfhost/config:/usr/src/app/config \
--volume /mnt/user/appdata/heaper-selfhost/thumbnails:/mnt/thumbnails \
--volume /mnt/user/appdata/heaper-selfhost/storage:/mnt/storage \
--platform linux/amd64 \
--network heaper \
ghcr.io/janlunge/heaper:latest

Docker Images

this will launch a postgres image with the ULID extension built in, and the heaper server stack.

ghcr.io/janlunge/heaper-postgres:latest - PostgreSQL with ULID extension
ghcr.io/janlunge/heaper:latest - All-in-one self-hosted server

Updating

To update your self-hosted instance:

# pull new version
docker pull ghcr.io/janlunge/heaper
# remove old image
docker container rm heaper-selfhost
# run the same command you did to start the container
# see your command above

Backup & Restore

Database Backup

docker exec heaper-selfhost-postgres pg_dump -U heaper heaper > backup.sql

Restore Database

docker exec -i heaper-selfhost-postgres psql -U heaper heaper < backup.sql

backing up the data and config directories for your actual files is recommended as well

--volume /mnt/user/appdata/heaper-selfhost/config:/usr/src/app/config \
--volume /mnt/user/appdata/heaper-selfhost/thumbnails:/mnt/thumbnails \
--volume /mnt/user/appdata/heaper-selfhost/storage:/mnt/storage \

Troubleshooting

Check Service Health

# Backend health
curl http://localhost:8080/api

# Sync server health
curl http://localhost:1234/sync/health

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f heaper-selfhosted

Next Steps

to use it in the heaper app, you first login to your cloud account then add a new server via the settings -> heaps -> pull heap

add the ip or hostname of the server INFO: ios and android devices do not support self signed ssl certs this means for proper tls encryption you need to either have a valid domain to get a real certificate for that you can place in the config/ssl folder