scalable, parallel, fault-tolerant Gemini server

5c9fc34 fix indentation in changelog

~slondr pushed to ~slondr/egalaxyd git

2 months ago

e372b89 update changelog and bump version number

~slondr pushed to ~slondr/egalaxyd git

2 months ago


egalaxyd provides a robust, parallel, fault-tolerant server for the Gemini and Spartan protocols. It is production-ready, although not fully battle tested.

egalaxyd really shines when run on a multi-core computer, and will take full advantage of the CPU resources it can get its hands on. Despite this, egalaxyd is very memory-efficient, and will typically not use more than 64 MB of memory even under heavy sustained load (in the realm of tens of thousands of simultaneous requests served on commodity hardware).

#Gemini support

egalaxyd supports basic server functionality. Properly-formed requests are usually handled correctly. Directory re-writing, MIME type support, and basic response codes are implemented. Application errors or erroneous requests do not cause the entire server to crash; egalaxyd is self-healing.

There is a list of features and bugfixes which guard the road to v1.0, tracked in <roadmap.md>.

#Spartan support

egalaxyd's spartan server is fairly complete. Properly-formed requests are handled correctly. There may be some rough edges with regards to configuration.

By default, egalaxyd listens for Spartan requests on port 3000. This is user-configurable.

No special attention is paid to the interactive portions of the Spartan protocol specification.

#Setup instrutions

#Quickstart with docker

Just docker run -it -p 1965:1965 -p 300:3000 tildegit.org/slondr/egalaxyd:latest. Boom, you are now serving content on Gemini at port 1965 and on Spartan at port 300. Yeah, it's that easy! (Assuming you had rights to port 300).

Note that the docker setup command creates an SSL certificate that is very well-known. It's useful to check your network setup by hitting localhost:1965 with a gemini client and seeing the hello world message, but if you get beyond that point you must delete the server.crt and server.key files and re-generate them using your actual domain information.

The container will serve files directly out of the /root/public directory by default, so just put more gmi files (or whatever you want to serve) there.

#Installing from source

This is the recommended way to install production instances of egalaxyd.

Run MIX_ENV=prod mix deps.get; mix release, and then executed the indicated start command (by default, _build/prod/rel/egalaxyd/bin/egalaxyd start). egalaxyd is now serving files on both Gemini and Spartan from your current working directory!

Make sure you start the application from a working directory containing the toml config file and your SSL certificate.


egalaxyd started life as a Gemini server named Geminex, which became feature-complete as a Gemini server by version 0.2. A separate but technically very similar spartan protocol server named Diarchy was written about six months later. In late July 2022, the project ambitions were merged into a single monolithic application, mainly out of a desire to implement Titan support for both servers at the same time.

The first version of the project under the name egalaxyd was 0.3, to represent a linear transition forward from geminex.


I wanted a Gemini server that is both braindead easy to use quickly (think like serve in the Node space or http.server in Python) and viable for serious production use.

In support of those goals, egalaxyd aims to implement reasonable conventions without necessary configuration, and strives for fault-tolerance and scalability.

If you want more of a marketing pitch, see this (now very-outdated) gemlog post (gemini://tilde.pink/~slondr/geminex.gmi).