Hyperion
The backend for hyperion.zone.
See the project vision for Hyperion's purpose, history, and proposed
direction.
Browser requirements
The React inbox uses Tailwind CSS 4 and requires Safari 16.4+, Chrome 111+,
or Firefox 128+ (including equivalent Chromium-based browsers). Older browsers
and wallet apps with older embedded browser engines are not supported by this
CSS build. See Tailwind's browser requirements.
Automated system tests run in Chromium. Safari, Firefox, and real wallet/mobile
flows still need the checks in browser wallets; passing the
Chromium suite does not establish compatibility with those environments.
Setup
git clone TODO
cd hyperion
bundle install
rake db:create
rake db:seed
Tests
Use the Ruby version in .ruby-version, Node version in .nvmrc (Node 26), and
PostgreSQL 16 to match CI.
Start the system PostgreSQL service before preparing the test database. On macOS
with Homebrew PostgreSQL 16 installed, this starts it now and at login:
brew services start postgresql@16
Rails connects through the local PostgreSQL socket as your operating-system user,
using hyperion_development for development and hyperion_test for tests.
Use DATABASE_URL to override the connection.
nvm use
RAILS_ENV=test bundle exec rails db:create db:schema:load
bundle exec rake test
Post heading links
Rendered headings have generated fragment IDs in API HTML and both preview
renderers. For example, # Real Heading becomes id="user-content-real-heading"
and can be targeted with [Jump](#real-heading). IDs use the rendered heading
text and Kramdown's basic ASCII slug convention; empty slugs use section.
Repeated or colliding names receive unique -1, -2, etc. suffixes within the
post. The user-content- prefix keeps author-controlled headings from colliding
with page IDs or window globals; the preview's fragment handling maps the bare
slug to the prefixed ID, so plain #slug links need that script.
IDs are generated after sanitization; author-supplied HTML and Markdown IDs
are not preserved. Fragment links scroll within the current preview. A direct
legacy sandbox URL can include a fragment, such as
/posts/42/content_sandbox#real-heading. The React preview still requires the
post to be selected; its fragments do not encode a post selection.
HiveSigner callbacks
Select the hyperion.zone app account at https://hivesigner.com/profile and
register these exact Redirect URIs, one per line:
https://hyperion.zone/sessions/authorized
https://www.hyperion.zone/sessions/authorized
https://hyperion.zone/api/v1/agent/auth_challenges/hivesigner_callback
https://www.hyperion.zone/api/v1/agent/auth_challenges/hivesigner_callback
Browser sign-in uses /sessions/authorized. Agent device-code sign-in uses
the fixed API callback and carries the challenge ID in OAuth state, which
HiveSigner returns to Hyperion. Do not include challenge IDs or scope=login
in the registered callback. Each callback must match the request's host and
path exactly. After deploying a callback change, start a fresh device challenge.
For local browser sign-in, also register
http://localhost:3000/sessions/authorized, then start a fresh login.
See browser wallets for provider capabilities, authentication
policy, rollout settings, and the desktop/mobile verification checklist.
HafSQL indexing
Post indexing uses HafSQL by default. It connects to the public HafSQL endpoint
by default:
host: hafsql-sql.mahdiyari.info
port: 5432
database: haf_block_log
user: hafsql_public
password: hafsql_public
Override the connection with HAFSQL_DATABASE_URL, or with HAFSQL_HOST,
HAFSQL_PORT, HAFSQL_DATABASE, HAFSQL_USERNAME, and HAFSQL_PASSWORD.
The default comments state relation is hafsql.comments. Override it with
HAFSQL_COMMENTS_RELATION when your HafSQL schema differs. The default column
names expect author, permlink, title, body, parent_author,
category, json_metadata, created, last_edited, and deleted;
override them with HAFSQL_COMMENTS_*_COLUMN env vars when needed. The public
view does not expose block or transaction IDs, so Hyperion stores 0 and an
empty transaction id unless HAFSQL_COMMENTS_BLOCK_NUM_COLUMN and
HAFSQL_COMMENTS_TRX_ID_COLUMN are configured.
Set HAFSQL_INDEXER_ENABLED=false to fall back to the original RPC stream
indexer.
Heroku
This repo includes Heroku process definitions for the Rails web process and
release-phase database migrations.
heroku create hyperion-zone
heroku buildpacks:set heroku/nodejs
heroku buildpacks:add heroku/ruby --index 2
heroku addons:create heroku-postgresql:essential-0
heroku config:set RAILS_ENV=production RAILS_LOG_TO_STDOUT=enabled RAILS_SERVE_STATIC_FILES=enabled
heroku config:set SECRET_KEY_BASE=$(openssl rand -hex 64)
git push heroku main
If you deploy from a branch other than main, push it explicitly:
git push heroku HEAD:main
Use Heroku Scheduler for periodic indexing. Add a Scheduler job that runs every
10 minutes:
bundle exec rake index:once
Post indexing uses the public HafSQL connection by default. Set
HAFSQL_DATABASE_URL or the individual HAFSQL_* config vars above if the
production app should use a different HafSQL endpoint.
Production diagnostics
Check dynos and recent releases:
heroku ps -a hyperion-zone
heroku releases -a hyperion-zone -n 5
Check the public health endpoint:
curl https://hyperion-zone-ddb79736a137.herokuapp.com/.well-known/healthcheck.json
Run read-only inbox and reputation diagnostics:
heroku run 'bundle exec rake ops:inbox[inertia]' -a hyperion-zone
heroku run 'bundle exec rake ops:reputation[inertia]' -a hyperion-zone
Use a narrow error scan when checking Heroku logs:
heroku logs -a hyperion-zone -n 1500 | rg -i '(^|[[:space:]])(at=error|level=error|status=5[0-9][0-9]|code=H10|code=H11|FATAL|Unhandled|ActiveRecord::|ActionController::|NoMethodError|NameError|PG::|RuntimeError)'
Avoid broad searches such as error|exception for routine checks. They can
false-positive on normal SQL text, account names, or blacklist data.
