Installation

This guide details installing Hashtopolis using Docker, the recommended method since version 0.14.0. Docker offers a faster, more consistent setup process.

Instructions for installing the bundled version can still be found on the Install without Docker page. However, please be aware that this method is not officially supported.

Requirements

• Instructions tested on Ubuntu 22.04 & Windows 11 (WSL2)
• Install docker, https://docs.docker.com/engine/install/ubuntu/ or https://docs.docker.com/desktop/install/windows-install/
• Install docker compose v2 https://docs.docker.com/compose/install/linux/#install-using-the-repository

When using WSL2, please enable Docker Compose V2 and WSL Integration in Docker Desktop.

Setup Hashtopolis

Using Docker hub

The official Docker images can be found on Docker Hub at: https://hub.docker.com/u/hashtopolis. Two Docker images are needed to run Hashtopolis: hashtopolis/frontend (setting up the web user interface), and hashtopolis/backend (taking care of the Hashtopolis database).

A docker-compose file allowing to configure the docker containers for Hashtopolis is available in this repository. Here are the steps to follow to run Hashtopolis using that docker-compose file:

1. Create a folder and change into the folder

   mkdir hashtopolis
   cd hashtopolis

2. Download docker-compose.yml and env.example

   wget https://raw.githubusercontent.com/hashtopolis/server/master/docker-compose.yml
   wget https://raw.githubusercontent.com/hashtopolis/server/master/env.example -O .env

3. Edit the .env file and change the settings to your likings.

   nano .env

4. Start the containers:

   docker compose up

5. Access the Hashtopolis UI through: http://127.0.0.1:8080 using the credentials (user=admin, password=hashtopolis)
6. If you want to play around with a preview of the version 2 of the UI, consult the New user interface technical preview section.

Build Hashtopolis images yourself

Alternatively, the Docker images can be built from source following these steps.

Build frontend image

1. Clone the Hashtopolis web-ui repository and cd into it.

   git clone https://github.com/hashtopolis/web-ui.git
   cd web-ui

2. Build the web-ui repo and tag it

   docker build -t hashtopolis/frontend:latest --target hashtopolis-web-ui-prod .

Build backend image

1. Move one directory back, clone the Hashtopolis server repository and cd into it:

   cd ..
   git clone https://github.com/hashtopolis/server.git
   cd server

2. (Optional) Check the output of file docker-entrypoint.sh. If it mentions 'with CRLF line terminators' your git checkout is converting line-ending on checkout, which is causing issues for files within the docker container. This is common behaviour for example within Windows (WSL) instances. To fix this:

   git config core.eol lf
   git config core.autocrlf input
   git rm -rf --cached .
   git reset --hard HEAD

   Check that file docker-entrypoint.sh correctly outputs: 'docker-entrypoint.sh: Bourne-Again shell script, ASCII text executable'

3. Copy the env.example and edit the values to your likings

   cp env.example .env
   nano .env

4. (Optional) If you want to test a preview of the version 2 of the UI, consult the New user interface technical preview section.

5. Build the server docker image

   docker build . -t hashtopolis/backend:latest --target hashtopolis-server-prod

Run and access Hashtopolis

1. Start everything

   docker compose up

2. Access the Hashtopolis UI through: http://127.0.0.1:8080. If you enabled the preview of the new Hashtopolis UI, you can access it through http://127.0.0.1:4200. The credentials of both UI are user=admin, password=hashtopolis by default. These values can be modified in the .env file.

Building behind an TLS-inspection/IDS firewall

• First source environmental variables (see .devcontainer/.env.sample for inspiration)

  source .devcontainer/.env

• Build container with arguments (replace with the build parameters provided in the previous section)

  export CONTAINER_USER_CMD_PRE CONTAINER_USER_CMD_POST
  docker build --build-arg CONTAINER_USER_CMD_PRE --build-arg CONTAINER_USER_CMD_POST <regular build command>

Air-gapped or offline network

If you are running Hashtopolis in an offline network or an air-gapped network, you will need to use a machine with internet access to either pull the images directly from the docker hub or build it yourself.

Here are the commands to pull the images from Docker hub. To build the images from source, follow the instructions in the section related to building images.

docker pull hashtopolis/backend:latest
docker pull hashtopolis/frontend:latest

The images can then be saved as .tar archives:

docker save hashtopolis/backend:latest --output hashtopolis-backend.tar
docker save hashtopolis/frontend:latest --output hashtopolis-frontend.tar

Next, transfer both file to your Hashtopolis server and import them using the following commands

docker load --input hashtopolis-backend.tar
docker load --input hashtopolis-frontend.tar

Continue with the normal docker installation steps found above

New user interface technical preview

NOTE: The APIv2 and UIv2 are a technical preview. Currently, when enabled, everyone through the new API will be fully admin!

To enable 'version 2' of the API:

1. Stop your containers
2. set the HASHTOPOLIS_APIV2_ENABLE to 1 inside the .env file.
3. docker compose up
4. Access the technical preview via: http://127.0.0.1:4200 using the credentials (user=admin, password=hashtopolis)