Make room for the story.

Before you begin

Ramus is self-hosted software. These instructions are for people comfortable with a terminal, environment settings and application hosting. No server or database is created by visiting this website.

The bundled installer supports macOS and Linux. A tested Windows installer is not available. Keep backups of your existing database and configuration, and use HTTPS before inviting family over the internet.

Connect to existing Gramps Web

Use this route when you already run Gramps Web. Ramus runs as a separate application and connects to your existing API. The guided connector wizard is still planned; configuration is currently manual.

1. Get the application source

git clone https://github.com/duncanabraham/ramus.git
cd ramus
npm ci

2. Configure your local process

Set your own API address, Gramps login name and Gramps person ID. The initial Ramus owner mapping uses that existing Gramps account. Replace every example value below; these values are not credentials for a working service.

export GRAMPS_BASE_URL='https://gramps.example.com/api'
export RAMUS_OWNER_USERNAME='your-gramps-login'
export RAMUS_OWNER_PERSON_ID='your-gramps-person-id'
export RAMUS_OWNER_FULL_NAME='Your display name'
export HOST='127.0.0.1'
export PORT='3210'
npm start

Open http://127.0.0.1:3210 on the machine running Ramus, then sign in with the configured Gramps account. A remote server needs a secure access route; its loopback address is not accessible from another computer.

The repository’s .env.example documents additional settings. Ramus does not automatically load a .env file: pass environment settings through your shell, container or process manager. Never commit real configuration or passwords.

3. Prepare family access

Configure your HTTPS address, secure reverse proxy and invitation/email settings as needed. Gramps authentication and Ramus access approval are separate parts of the installation. Review access before inviting relatives.

Start with a new, empty tree

The bundled installer runs Ramus, the official pinned Gramps Web service, its background worker and supporting data service through Docker Compose. It creates a separate empty tree. It does not import your current family data automatically.

1. Build the installer from source

Use Node.js, Python 3 and Git on the build machine. Choose a fresh output directory. If you have already cloned the repository, start from its root and skip the first two lines.

git clone https://github.com/duncanabraham/ramus.git
cd ramus
bash scripts/build-release.sh --output /tmp/ramus-release-0.1.1

The output contains ramus-0.1.1.zip, a source export and a checksum report. Extract the ZIP, open a terminal in its ramus-0.1.1 folder, and run:

./install.sh

The installer checks Docker, Docker Compose and OpenSSL. If prerequisites are missing, it explains the proposed installation and asks before installing them. It then prints a private setup link for creating the first owner.

The default installation directory is ~/Ramus on macOS and /opt/ramus on Linux. You can select another dedicated directory:

./install.sh --directory /srv/ramus

Updates & support

Keep application code separate from private installation data. Back up before upgrading. The bundled Gramps Web image is pinned for compatibility; avoid changing it to latest independently.

See the Ramus repository for the current source and documentation. Report problems through GitHub Issues. Use invented examples when reporting an issue, and remove names, family records, passwords and server details from screenshots and logs.

← Back to Ramus