Why Self-Hosting Heaper?

Jan Lunge

Jan Lunge

— 2 min read

Self-hosting Heaper provides you with full control over your data, offering a level of security and flexibility that is not possible with cloud services. By running Heaper on your own hardware, you ensure that your data is private and always accessible, even if the company behind Heaper ceases to operate. This guide explains the benefits of self-hosting Heaper and provides the initial steps to get you started.

Full Control Over Your Data

When you self-host Heaper, you retain complete control over your data. Instead of relying on third-party services, your information stays in your hands. This means that even in the unlikely event that the company behind Heaper shuts down, your data and access to Heaper will remain intact. Self-hosting ensures that your data remains private, secure, and under your management, giving you peace of mind.

Containerized Architecture

Heaper is designed to be self-hosted using Docker containers. It runs a Go-based backend and uses ArangoDB, a graph-based NoSQL database, for data storage. This setup provides you with a powerful backend that is easy to manage and scale. ArangoDB also includes an explorer that lets you access and manage your data without requiring any coding experience.

Access Heaper from Anywhere

For maximum flexibility, Heaper can be run on a NAS or server within your home network, allowing you to access your self-hosted Heaper instance remotely. Whether through port forwarding or a VPN, you can manage your Heaper instance from anywhere, giving you the ability to stay productive even on the go.

Getting Started

Step 1: Install Docker

To run Heaper, you’ll need Docker installed on your system. Docker simplifies the process of running Heaper by isolating its dependencies in containers, making it easier to maintain and update.

If you’re new to Docker, you can download Docker Desktop here.

Step 2: Set Up the Database

Heaper uses ArangoDB for data storage. To start the database, run the following Docker command:

docker run -d -p 8529:8529 -e ARANGO_ROOT_PASSWORD=password -v /tmp/arangodb:/var/lib/arangodb3 --name arangodb-instance arangodb

This will launch ArangoDB and expose it on localhost:8529. You’ll need to create a new database for Heaper within the ArangoDB interface.

Step 3: Run Heaper

Once the database is set up, you can start Heaper. Use the following Docker command to run Heaper with the necessary environment variables:

docker container run \
--restart unless-stopped \
-v /mnt/user/appdata/heaper/config:/usr/src/app/config \
-v /mnt/user/appdata/heaper/ssl:/usr/src/app/ssl \
-e DB_HOST=http://10.0.1.1:8529 \
-e DB_NAME=heaper \
-e DB_PASS=password \
-e HTTPS_ENABLED=true \
-p 3000:3000 \
-d \
--name heaper \
ghcr.io/janlunge/heaper:latest

Note that when enabling HTTPS (HTTPS_ENABLED=true), you’ll need to supply your own SSL certificates, which should be placed in the ssl directory.

Step 4: Login and Configure

Once Heaper is running, you can log in with the default credentials (admin), and you’ll be able to change your username and password in the settings. This is also where you can find your user ID.

Your user ID is important because it allows you to map specific folders to individual users in the container. This means you can configure personal storage locations for different users on your system.

Step 5: Map Folders for Storage

To map folders for users, you’ll need to specify directories for items like thumbnails and user-specific storage. Here’s an example of how to map folders for a specific user:

docker container run \
--restart unless-stopped \
-v /mnt/user/appdata/heaper/config:/usr/src/app/config \
-v /mnt/user/appdata/heaper/thumbnails:/mnt/thumbnails \
-v /mnt/user/PersonalFiles:/mnt/storage/01JAXVAZJGXJNEPH9T1BMAQNDG/Workspace \
-v /mnt/user/appdata/heaper/ssl:/usr/src/app/ssl \
-e DB_HOST=http://10.0.1.1:8529 \
-e DB_NAME=heaper \
-e DB_PASS=password \
-e HTTPS_ENABLED=true \
-p 3000:3000 \
-d \
--name heaper \
ghcr.io/janlunge/heaper:latest

This command ensures that user data is mapped correctly for previews and file storage, allowing Heaper to function as a multi-user environment.

Read more