Manual Install

This guide is to help you manually install Hamabē into your server machine.

Prerequisites

• Linux or FreeBSD
• Java Runtime Environment (JRE) 21 or later
• PostgreSQL 14 or later
• Reverse Proxy (e.g., Nginx, Caddy, Traefik, Apache, ...)
• LiveKit Server Optional
• Object Storage (e.g., Minio, Garage, Amazon S3, ...) Optional
• Email Server Optional

Minimum System Requirements

• 1 CPU vCore
• 1 GB RAM
• 10 GB storage

Setup

The commands below assume that the current dirrectory of your shell is the working directory of Hamabē, e.g., /opt/hamabe.

Get Latest Hamabē

Download the latest Hamabē server with:

curl -O https://releases.hamabe.space/latest-unstable.jar
curl -fsS https://releases.hamabe.space/latest-unstable.jar.sha256 | sha256sum -c  # Verify checksum (Optional)
mv latest-unstable.jar hamabe.jar

INFO

Only unstable versions are currently available. We will update the download link once we release the first stable version.

Prepare Config File

Save the following to config/application.properties which is the default location of Hamabē config file.

hamabe.domain=<your-instance-domain>
quarkus.http.host=0.0.0.0
quarkus.http.port=8080

Replace <your-instance-domain> to the domain for your instance. You can change the listen address and port of Hamabē via quarkus.http.host and quarkus.http.port.

DANGER

Do NOT change hamabe.domain after your instance has already run once, or federation issues are very likely.

TIP

You can specify a different path for the config file. To do so, add -Dquarkus.config.locations to the command line arguments of Java, for example:

java -Dquarkus.config.locations=file:///etc/hamabe/config.properties -jar hamabe.jar ...

Alternatively, you can specify the location of the config file via environment variable QUARKUS_CONFIG_LOCATIONS, for example:

env QUARKUS_CONFIG_LOCATIONS=file:///etc/hamabe/config.properties java -jar hamabe.jar ...

Prepare Database

First, create a new PostgreSQL user (e.g., hamabe) with:

sudo -iu postgres createuser -P hamabe

Then, create a new database (e.g., hamabe-main) with:

sudo -iu postgres createdb -O hamabe -E UTF8 hamabe-main

Install PGroonga Extension

Hamabē employs PGroonga, a PostgreSQL extension, as a full-text search engine.

Install PGroonga by following the official guide, and then enable PGroonga in the database with:

sudo -iu postgres psql -c "create extension pgroonga;" hamabe-main

Add Database Settings to Config File

Once you have created the database, add the following to the config file:

hamabe.database.name=hamabe-main
hamabe.database.username=hamabe
hamabe.database.password=<your-password>
hamabe.database.host=127.0.0.1
hamabe.database.port=5432

Replace the above values to those you specified when creating PostgreSQL database.

TIP

hamabe.database.host can be the path to the unix socket of PostgreSQL, for example:

hamabe.database.host=/var/run/postgresql/.s.PGSQL.5432

In this case, hamabe.database.port will be ignored.

Prepare Scheduler Database Optional

By default, Hamabē stores background job data of queue scheduler in the main database (e.g., hamabe-main).

If you plan to run the queue workers of Hamabē in different machines to scale your instance up horizontally, it is recommended to create a new database (e.g., hamabe-queue) for queue scheduler so that you can easily migrate the background job data later.

sudo -iu postgres createdb -O hamabe -E UTF8 hamabe-queue

Add Scheduler Database Settings to Config File

Once you have created the scheduler database, add the following to the config file:

hamabe.queue.database.name=hamabe-queue
hamabe.queue.database.username=hamabe
hamabe.queue.database.password=<your-password>
hamabe.queue.database.host=127.0.0.1
hamabe.queue.database.port=5432

Replace the above values to those you specified when creating the scheduler database.

TIP

hamabe.queue.database.host can be the path to the unix socket of PostgreSQL, for example:

hamabe.queue.database.host=/var/run/postgresql/.s.PGSQL.5432

In this case, hamabe.queue.database.port will be ignored.

Prepare Storage

Hamabē stores uploaded files to either local storage or object storage. In general, local storage is easy to setup and would be enough for small instances, while object storage is recommended for medium/large instances.

Setup Local Storage

To use local storage, add the following to the config file:

hamabe.storage.local-path=<your-local-path>

Change <your-local-path> to the desired directory where the user to run Hamabē has read and write permissions. Then, create the directory with:

mkdir -p "<your-local-path>"

Setup Object Storage

To use object storage, first create a bucket of your S3-compatible server for Hamabē, and add the following to the config file:

hamabe.storage.s3.enabled=true
hamabe.storage.s3.bucket=<your-bucket>
hamabe.storage.s3.endpoint=<your-endpoint>
hamabe.storage.s3.region=<your-region>
hamabe.storage.s3.key-id=<your-key-id>
hamabe.storage.s3.secret-key=<your-key-secret>
hamabe.storage.s3.path-style=false
hamabe.storage.s3.set-public-read=false
hamabe.storage.public-url=<your-public-url>

Replace the above values to those you specified with your S3-compatible server. Note that hamabe.storage.s3.path-style and hamabe.storage.s3.set-public-read depend on your bucket configuration.

<your-public-url> is a publicly accessible URL to your object storage. For example, if you want uploaded files to be accessed via https://storage.example.com/..., set https://storage.example.com to <your-public-url>.

TIP

It is recommended to setup a proxy server (or CDN) to your object storage and set <your-public-url> to the proxy URL, since it makes migration of your object storage easier.

Prepare LiveKit Optional

If you are letting users in your instance host Spaces (voice call), you need LiveKit.

There are a couple of options to setup LiveKit:

• LiveKit Cloud (SaaS)
• Self-hosting

In either way, Hamabē needs the following information of LiveKit:

• Endpoint URL
• API Key
• API Secret

TIP

LiveKit server can be installed in a different server from Hamabē, which is recommended if you plan to scale your instance up later. It is even possible to share the same LiveKit server among multiple Hamabē instances.

Self-Hosting LiveKit Server

INFO

To setup LiveKit server using Container such as Docker or Podman, follow the official deployment guide.

To manually install LiveKit server:

1. Download or build LiveKit server via the official repository, and place the executable binary of LiveKit to your desired path, e.g., /usr/local/bin/livekit-server.

2. Edit and place the config file in a directory where LiveKit server can read, e.g., /etc/livekit/config.yaml. Make sure that the ports specified in the config file are open on your firewall. Refer to the LiveKit documentation for details.

TIP

You need to set API kay and secret in the config file, which can be generated with:

livekit-server generate-keys

3. Configure your init system (e.g., systemd or rc.d) to automatically start LiveKit server at system startup. For systemd, an example service file is available here.

4. Configure the reverse proxy. The following is an example Caddyfile for Caddy.

livekit-turn.<your-domain> {
  reverse_proxy 127.0.0.1:5349
}
livekit.<your-domain> {
  reverse_proxy http://127.0.0.1:7880
}

Add LiveKit Settings to Config File

Once you have setup LiveKit, add the following to the config file:

hamabe.livekit.enabled=true
hamabe.livekit.url=<your-endpoint>
hamabe.livekit.api-key=<your-api-key>
hamabe.livekit.api-secret=<your-api-secret>

Replace <your-endpoint> to the endpoint URL of your LiveKit server, and <your-api-key> and <your-api-secret> to those in the LiveKit config file.

Prepare Email Server

INFO

Hamabē does not require email server to run, although it is strongly recommended to configure one. If you do not want to use email server, add the following to the config file:

quarkus.mailer.mock=true

This makes Hamabē output all email messages to the standard output.

To specify an email server for Hamabē, add the following to the config file:

quarkus.mailer.auth-methods=PLAIN LOGIN
quarkus.mailer.host=<smtp-server-address>
quarkus.mailer.username=YOUREMAIL@example.com
quarkus.mailer.password=YOURPASSWORD
quarkus.mailer.from=YOUREMAIL@example.com

Replace the above values to those you need to connect your SMTP server.

If your SMTP server requires STARTTLS to connect, add the following to the config file:

quarkus.mailer.port=587
quarkus.mailer.start-tls=REQUIRED

If your SMTP server requires implicit TLS to connect, add the following to the config file:

quarkus.mailer.port=465
quarkus.mailer.tls=true

Start Hamabē Server

First, migrate the database with:

java -jar hamabe.jar database migrate

After the database migration completes, start the server with:

java -jar hamabe.jar serve

Once Listening on ********:**** has been logged in the standard output, Hamabē server is running successfully. You can stop the server by Ctrl-C.

TIP

You can migrate the database at the server startup with:

java -jar hamabe.jar serve -run-migrations

Configure Init System

Configure your init system to automatically launch Hamabē server at system's startup.

For systemd, an example service file is available here.