Why Self-Hosting Heaper?

Jan Lunge

Jan Lunge

— 4 min read
Why Self-Hosting Heaper?
Photo by Alex Cheung / Unsplash

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.

there are 2 ways to work with docker, either you run each container as a command or you have their state and environment managed with docker-compose. we will show both ways here

Step 2: using docker

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.

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 2: using docker compose

first create the web network to map both containers together

docker network create web

services:
  arangodb:
    image: arangodb/arangodb:3.10.13
    # its more secure to not expose the datase port
    # ports:
    #  - "8529:8529"
    networks:
      - web
    environment:
      - ARANGO_ROOT_PASSWORD=maythetagsbewithyou
    volumes:
      - ./heaper/arango_data:/var/lib/arangodb3
      - ./heaper/arango_apps:/var/lib/arangodb3-apps
      - ./heaper/backups:/mnt/dbbackups

  heaper:
    # image: ghcr.io/janlunge/heaper:latest
    build:
      context: .
      dockerfile: Dockerfile
      target: combined
      args:
        - VERSION=dev-version
        - VITE_APP_VERSION=dev-version
        - VITE_APP_BUILD_TIME=dev-build-time
        - VITE_APP_COMMIT_HASH=dev-commit-hash
    platform: linux/amd64
    ports:
      - "3000:3000"
    environment:  
      - DB_HOST=http://arangodb:8529
      - DB_USER=root
      - DB_NAME=heaper
      - DB_PASS=maythetagsbewithyou
      - HTTPS_ENABLED=true
    # you can also use a .env file
    # env_file:
    #   - .env.local
    depends_on:
      - arangodb
    networks:
      - web
    volumes:
      - ./heaper/config:/usr/src/app/config
      - ./heaper/thumbnails:/mnt/thumbnails
      - ./heaper/storage:/mnt/storage
    # - /Users/janlunge/Documents:/mnt/storage/01JHQXJNZFVAV487BH4TFTGM1H/W2
networks:
  web:
    name: web
    external: true

and run this with docker-compose up

If you change the root password for arangodb also change the credentials in the heaper config to connect to the db, to use the arangodb web interface please choose a password without special characters. the password is only set during container creation for the db so you need to clear its data if you want to change the root pw later without using the web interface at port 8529

Step 3: Login and Configure

open the web interface at the ip address of your server with the port 3000 (you can change the mapping of this port in the docker compose eg. 3005:3000 to map it to port 3005) for example go to https://localhost:3000/ to make your browser always trust the certificate double click on the cert file in config/ssl/server.crt and set it to always trust.

Once Heaper is running, you can log in with the default credentials (admin, "may the tags be with you"), and you’ll be able to change your username and password in the settings. This is also where you can find your user ID. you can find the user id also from the storage/USERID folders.

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 4: Map Folders for Storage

To map folders for users, you’ll need to specify directories for items like thumbnails and user-specific storage.

if you used the docker way you will need to remove the container with docker container rm heaper and then recreate it with the new config, the data is saved in volume mounts and the database so you will not lose data by destroying the container.

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.

with the docker compose way you just add the volume mapping like the Documents folder in the docker-compose and restart the heaper container with docker-compose stop heaper and docker-compose up -d heaper

Read more