You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Jansen Price 3ec4797183 Update README with php extension dependencies 2 years ago
bin Correctly ingest key passphrase for server key 2 years ago
config Add Makefile to install as systemctl service 2 years ago
src/Orbit Add installation and usage details to README 2 years ago
tests Correct tests for version check 2 years ago
.gitignore Clean up during testing, add module interface 2 years ago
LICENSE Initial commit 2 years ago
Makefile Correct some order of operations in make install 2 years ago Update README with php extension dependencies 2 years ago
composer.json Add PHP version dep in composer file 2 years ago
composer.lock Minor upgrade in one dependency (lock file) 2 years ago
orbit.service Add Makefile to install as systemctl service 2 years ago

🛰 Orbit

Server for gemini protocol written in PHP


  • PHP 7.x or higher
  • composer (see for download/install instructions)

For dev dependencies:

  • php-xml
  • php-mbstring

You can install PHP + required dev extensions on debian-based linux with

sudo apt install php-cli php-xml php-mbstring


Clone this repository to a suitable location.

git clone

Fetch composer dependencies.

cd orbit
composer update

You can choose to do composer update --no-dev to not include the dev dependencies (to run unit tests).


After installation, you can invoke the service with bin/orbit. You should pass in some important configuration options. See the configuration section below for more details.


For a quickstart, you can do the following:

sudo mkdir /var/gemini
sudo sh -c 'echo "# Hello world\n\nServer is running" > /var/gemini/index.gmi'
bin/orbit -c config/localhost.ini --dev

This will create a new directory to be the root of your gemini server at /var/gemini. Then we create an example index file at the root of the server. Then we run orbit pointing to the config file at config/localhost.ini. Running orbit with the --dev flag will automatically create the server key and cert files.

Install as service

To install as a service on your GNU/Linux machine, take a look at the orbit.service file in this repository.

An accompanied Makefile in this repository will assist you in setting up as a service (only works on GNU/Linux). Change "localhost" in the command below to whatever the hostname for your server should be.

sudo make install ORBIT_HOSTNAME=localhost

This will perform the following steps:

  • Symlink the orbit bin script at /usr/local/bin/orbit
  • Create config file at /etc/orbit/config.ini
  • Create self-signed cert for you at /etc/orbit/certs
  • Create a new non-login user gemini-data for the service to use
  • Create service file at /etc/systemd/system/orbit.service

Once this completes successfully, you may edit the config file to your liking, or install your own cert files. The default location of the server root is /var/gemini.

To start the service run sudo systemctl start orbit or sudo service orbit start


Run bin/orbit --help to get some helpful command line invocation options.

$ bin/orbit --help
Orbit 0.4
Usage: orbit [options]

  -c, --config <arg>   Use specified config file (.ini) for configuration
      --host <arg>     Set host/ip address to listen on (default
  -p, --port <arg>     Set port to listen on (default 1965)
      --hostname <arg> Set hostname of server (default localhost)
      --tls-cert <arg> Set cert PEM file to use (default null)
      --tls-key <arg>  Set private key PEM file to use (default null)
      --tls-passphrase <arg> Set passphrase for private key
      --root-dir <arg> Set the file root directory
      --log <arg>      Set log filename (default orbit.log)
      --dev            Allow developer server functions (default false)
  -h, --help           Show help
  -v, --verbose        Include more verbose output
  -q, --quiet          Print less messages
      --no-color       Don't use color output
      --version        Show version and exit


Most configuration options are available to be set at the invocation of orbit. The option -c allows you to define a path to a config file to define any configuration options not specified as command arguments.

; Example Orbit config file

; Host : The IP address designation that orbit should listen on
host = ""

; Port : the port that orbit should listen on
port = 1965

; Hostname : the expected domain that orbit is serving
hostname = ""

; TLS cert file : The location to the cert file
tls_certfile = "/etc/orbit/"

; TLS key file : The location to the private key for the server
tls_keyfile = "/etc/orbit/"

; Key passphrase : optional passphrase for server key
key_passphrase = ""

; Log file : where orbit should log information
log_file = "/var/log/orbit/orbit.log"

; Log level : Only log messages that are at or above this level
; Possible values (from low to high):
; - debug
; - info
; - notice
; - warning
; - error
; - critical
; - alert
; - emergency
log_level = "info"

; Root dir : Root directory of the server files
root_dir = "/var/gemini"

; Index file : Name of the index file (when a directory is accessed)
index_file = "index.gmi"

; Enable directory index : Whether orbit should serve up a directory listing
; for directories accessed that have no index file present
enable_directory_index = true


The host config option is the IP address the server should bind to. Examples include (to listen on all ipv4 addresses), or [::] to listen on all ipv6 addresses.

In a config file, the option is specified with host = "". From the command line arguments, the option is specified with --host


The port config option is which port the server will listen for incoming connections. The default for gemini is 1965, but orbit can be bound to any port that is available.

If the port is not available, you will see the following error message "Exception: Error 0: Address already in use"

In a config file, the option is specified with port = 1965. In command line arguments, the option is specified with --port 1965


The hostname config option tells orbit which hostname the server is serving. It will deny requests that do match this domain.

Config file option: hostname = localhost. Command line arg: --hostname localhost

TLS cert file

The TLS cert file config option allows you to define the path to the cert file in PEM format.

Config file option: tls_certfile = "/path/to/cert.pem". Command line arg: --tls-cert /path/to/cert.pem.

TLS key file

The TLS key file config option allows you to define the path to the private key file for the server in PEM format.

Config file option: tls_keyfile = "/path/to/key.pem". Command line arg: --tls-key /path/to/key.pem.

Key passphrase

If the private key requires a passphrase, you can specifiy it in the config option.

Config file option: key_passphrase = "secret". Command line arg: --tls-passphrase secret.

Log file

The log file config option allows you to define the location where the orbit log file should write to. It must be writable by the user used to launch orbit.

Config file option: log_file = "/path/to/orbit.log". Command line arg: --log path/to/orbit.log.

Log level

The log level config option allows you to specify the log level of the messages written to stdout or the log file. The levels are debug, info, notice, warning, error, critical, alert, emergency. Only log messages at or above the level specified will be include.

Config file option: log_level = "info".

It is not possible to set granular levels with the command line arguments. The default is 'info'. If you use the -v or --verbose option, it will set the log level to 'debug'.

Root directory

The root directory config option allows you to specify the path that is the root directory of the server.

Config file option: root_dir = "/var/gemini". Command line arg: --root-dir /var/gemini.

Index file

If a request is made for a directory, orbit will look in the directory for the index file and serve it. Define what the name of this file will be by setting the index file config option. The default is "index.gmi".

Config file option: index_file = "index.gmi".

Enable directory index

If a request is made for a directory and there is no index file in the target directory, orbit can optionally return a list of files/directories within that directory. To turn this on, set the enable directory index config option. The default is to for this to be enabled.

Config file option: enable_directory_index = true.

--dev option

The --dev command line argument flag tells orbit that this is a development server environment. When this is enabled, orbit will automatically create a self-signed cert at runtime.

-q / --quiet option

The --quiet command line argument flag tells orbit to not output anything to stdout.