hirgon

Messenger of Gondor.

DESCRIPTION

hirgon is a web application for scheduling message content.

Messages may be added, deleted, set active, or scheduled to be made active at a later date.

NOTE: this project is still WIP and missing several key features...

INSTALLATION

install system dependencies

• git
• npm
• nodejs
• postgresql
• redis
• make

install and setup the application

git clone git@github.com:booksmith-io/hirgon.git
cd hirgon
npm run setup
cp -a .hirgonrc.example .hirgonrc

configuration

The configuration file contains the following keys and values:

app

The app section defines the application specific configuration.

"app": {
    "name": "hirgon",
    "port": 5000,
    "address": "0.0.0.0"
}

• name is required and controls the name of the running app
• port is required and is the port to bind the app to when running the application
• address is required and is the IP address to bind the app to when running the application

session

The session section defines the development and production session secret keys.

"session": {
    "secret": {
        "development": "keyboard-cat",
        "production": ""
    }
}

Both development and production are required for the environment the application is being run.

production is autogenerated when building the docker container.

database

The database section defines the PostgreSQL connection details.

"database": {
    "host": "localhost",
    "port": 5432,
    "name": "hirgon",
    "user": "hirgon",
    "password": "hirgon",
    "ssl": 0
}

• host is required and is the PostgreSQL host name
• port is required and is the PostgreSQL TCP port
• name is required and is the database name
• user is required and is the database role/user name
• password is required and is the database password
• ssl is required and takes either 0 or 1 to disable or enable SSL

ratelimits

The ratelimits section controls enabling and configuring ratelimiting per IP.

"ratelimits": {
    "enabled": 0,
    "requests_threshold": 7,
    "block_seconds": 300
}

• enabled is required and takes either 0 or 1 to disable or enable
• requests_threshold is required and takes a positive integer for how many requests per second before the IP is blocked
• block_seconds is required and takes a positive integer for how many seconds the IP is blocked after reaching the requests_threshold

redis

The redis section defines the Redis connection used for sessions and distributed ratelimiting.

"redis": {
    "host": "localhost",
    "port": 6379,
    "password": "",
    "db": 0,
    "tls": 0
}

• host is required and is the Redis host name
• port is required and is the Redis TCP port
• password is optional and may be an empty string when auth is disabled
• db is required and is the Redis database number (0 or greater)
• tls is required and takes either 0 or 1 to disable or enable TLS

user_agent_blocks

The user_agent_blocks section controls enabling and configuring user agents that shouldn't be allowed to access the app.

"user_agent_blocks": {
    "enabled": 0,
    "user_agents": [
        "facebookexternalhit",
        "facebookscraper",
        "amazonbot",
        "Cortex-Xpanse"
    ]
}

• enabled is required takes either 0 or 1 to disable or enable
• user_agents is required and takes an array of user agent strings to match for blocking access
  • if a user agent in the list is making the request, a 406 (unacceptable) is returned
  • the user agent string is case insensitive and can be found anywhere in the user agent string making the request
  • the array is required but may be empty

run the development server

npm run development

update the application

npm run upgrade
npm run update_deps
npm run upgrade_database

run through docker

# development - start in background (detached)
docker-compose --profile dev up -d --build

# development - restart to pick up code changes
docker-compose --profile dev restart

# development - view logs
docker-compose --profile dev logs -f

# production - connects to external postgresql via .hirgonrc
docker-compose --profile prod up -d

For production container orchestration (ECS/Fargate or similar):

• set HIRGON_DB_* environment variables for remote PostgreSQL
• set HIRGON_REDIS_* environment variables for remote Redis
• run migrations in deployment automation before rolling app tasks
• app service tasks never run database patches during container startup
• terminate HTTPS at the frontend load balancer/proxy

run in production (not through docker)

add to systemd

cat << EOF > /etc/systemd/system/hirgon.service
[Service]
RuntimeDirectory=hirgon
ExecStart=/path/to/npx pm2-runtime start ecosystem.config.js
WorkingDirectory=/home/hirgon/git/hirgon/
Restart=always

StandardError=syslog
SyslogIdentifier=hirgon

Type=simple
User=hirgon
Group=hirgon

Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target
EOF

systemctl enable hirgon.service
systemctl start hirgon.service

add the proxy configuration to the webserver

apache2

within the appropriate vhost

ProxyPreserveHost on
ProxyPass / http://localhost:5000/
ProxyPassReverse / http://localhost:5000/

nginx

within the appropriate vhost

location / {
    proxy_pass         http://localhost:5000;
    proxy_http_version 1.1;
    proxy_set_header   Host $host;
}

TESTING

This repo has two github actions installed which help ensure quality of the project.

Both actions run on push and pull_request for the main branch.

Test

The Test action runs two stages. Both stages must pass for the PR to be merged.

lint

The lint stage verifies tidiness through eslint.

test

The test stage verifies the unit tests all pass.

Docker Build Test

The Docker Build Test action verifies the docker image and containers build, explicitly using the docker-compose files to ensure they work as expected.

The test verifies several things:

• the server full starts
• the /login route returns without failure
• users can be created
• authentication with those users is successful
• expected content is found on /

The Docker Build Test action must pass for the PR to be merged.

COPYRIGHT AND LICENSE

hirgon is Copyright (c) 2025 Blaine Motsinger under the MIT license.