Terminus is a Ruby/Hanami web server that allows you to manage TRMNL devices running on your own local network or hosted cloud. This is our flagship BYOS implementation that aims to be compatible with our TRMNL Core server but also different since this open source solution provides features not possible in our Core application.
-
Provides privacy first functionality by empowering you to run your own private server, network, and devices. You own the stack and the data. 🎉
-
Uses esbuild for asset management.
-
Uses htmx for Hypermedia-Driven user interfaces.
-
Uses ImageMagick for image processing.
-
Uses Overmind for running multiple processes.
-
Uses PostgreSQL for the database.
-
Uses Puma for the server.
-
Uses Rodauth for authentication.
-
Uses Sidekiq for worker jobs.
-
Uses Valkey for the key/value cache.
-
Supports YJIT.
-
Supports Docker.
-
Supports TRMNL devices.
The following is a high level overview you can use to compare/contrast when deciding between using this Build Your Own Server (BYOS) implementation or our hosted solution.
Legend
-
⚪️ Planned.
-
🟢 Supported.
-
🟡 Partially supported.
-
🔴 Not supported, not implemented, or isn’t applicable.
Matrix
The following documents the features supported in this implementation which are similar to our TRMNL Core server. While we aim to be compatible with Core, the experience will be slightly different in look, feel, and behavior.
| Terminus | Hosted | |
|---|---|---|
Dashboard |
🟢 |
🟢 |
Devices |
🟢 |
🟢 |
Sensors |
🟢 |
🟢 |
API |
🟢 |
🟢 |
Screens |
🟢 |
🟢 |
Playlists |
🟢 |
🟢 |
Extensions |
🟢 |
🟢 |
Models |
🟢 |
🟢 |
Palettes |
🟢 |
🟢 |
Firmware |
🟢 |
🟢 |
Accounts |
🟢 |
🔴 |
Users |
🟢 |
🟢 |
Docker |
🟢 |
🔴 |
-
Git.
-
Ruby.
-
Node.
-
Valkey: Can be swapped out for Redis or Dragonfly if desired.
-
Haskell Dockerfile Linter (optional, for development): For
Dockerfilelinting. -
Google Chrome (optional, for development): For screen generation via the headless browser.
-
Overmind (optional, for development): Uses your
Procfileto launch processes. -
Docker (optional when only using Ruby).
-
TRMNL device (optional, you can use virtual devices).
To immediately spin up Terminus on your local machine using Docker, run:
curl https://raw.githubusercontent.com/usetrmnl/terminus/refs/heads/main/scripts/docker/quick.sh | bashOnce launched, open http://localhost:2300 in your browser then click the Register link to register and log into the system.
To set up this project for local development, run:
git clone https://github.com/usetrmnl/terminus
cd terminus
bin/setup💡 The setup script is idempotent so you can run it multiple times without harm. To rebuild a file managed by the setup script, delete the desired file and rerun setup to recreate.
To upgrade this project for local development, run:
cd terminus
bin/upgradeWatch for any changes that need to be addressed in the output. Otherwise, if no changes are detected, you are set.
To launch the server, run:
# Development
overmind start --port-step 10 --procfile Procfile.dev --can-die assets,migrate
# Production
overmind start --port-step 10 --can-die assets,migrateTo view the app, use either of the following:
-
Secure: https://localhost:2443
-
Insecure: http://localhost:2300
From your browser, you can then click on the Register link to register and log into the system.
See Configuration documentation for details.
When launching this application for the first time, there will be no users. The first user to register will automatically be given Verified status along with full access to the system. All subsequent users will marked as Unverified and must be manually Verified in order to have access to the system. In the future, more fine grained control will be provided for individual users, roles, and permissions.
Also, once logged in, you can manage your settings as follows:
-
Visit
/me/loginto update your email address. -
Visit
/me/passwordto update your password. -
Visit
/me/rememberto enable, disable, or forget if you should be remembered.
See Devices documentation for details.
In accordance with the Unbrickable Pledge, the latest version of Terminus always supports the latest version of our Firmware. If you are running on older firmware, you’ll need to use an older version of Terminus. Here’s a rough breakdown of the Firmware version history where changes were applied that might cause issues if you haven’t upgraded your devices in a while:
See Extensions documentation for details.
See API documentation for details.
See Docker documentation for details.
See Raspberry PI documentation for details.
See Kubernetes documentation for details.
See Render documentation for details.
See Development documentation for details.
While this project is distributed under the permissive MIT License, we strongly believe that technology should serve humanity’s best interests. We created this software with the intent that it be used to benefit people and communities, not to cause harm. We encourage individuals and organizations to consider the ethical implications and to use this project in ways that respect human rights, promote equity, and contribute positively to society. Though we cannot legally restrict usage under the MIT License, we ask that you join us in fostering a responsible technology ecosystem by avoiding applications that could cause harm, perpetuate discrimination, or undermine human dignity. Technology is best used to enrich lives, let’s ensure we build a better world together!
-
Built with Hanamismith.
-
Engineered by TRMNL.