sumpygump / orbit
Server for gemini protocol
Requires
- php: >=7.2
- monolog/monolog: ^2.1
- neitanod/forceutf8: ^2.0
- sumpygump/qi-console: ^1.3
Requires (Dev)
- phpunit/phpunit: ^9.3
This package is not auto-updated.
Last update: 2024-11-06 10:30:38 UTC
README
Server for gemini protocol written in PHP
Dependencies
- PHP 7.x or higher
- composer (see getcomposer.org 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
Installation
Clone this repository to a suitable location.
git clone https://tildegit.org/sumpygump/orbit.git
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).
Setup
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.
Quickstart
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-datafor 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
Usage
Run bin/orbit --help to get some helpful command line invocation options.
$ bin/orbit --help
Orbit 0.4
Usage: orbit [options]
Options:
-c, --config <arg> Use specified config file (.ini) for configuration
--host <arg> Set host/ip address to listen on (default 0.0.0.0)
-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
Configuration
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 = "0.0.0.0"
; Port : the port that orbit should listen on
port = 1965
; Hostname : the expected domain that orbit is serving
hostname = "example.com"
; TLS cert file : The location to the cert file
tls_certfile = "/etc/orbit/example.com.cert.pem"
; TLS key file : The location to the private key for the server
tls_keyfile = "/etc/orbit/example.com.key.pem"
; 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
Host
The host config option is the IP address the server should bind to. Examples include 0.0.0.0 (to listen on all ipv4 addresses), or [::] to listen on all ipv6 addresses.
In a config file, the option is specified with host = "0.0.0.0". From the command line arguments, the option is specified with --host 0.0.0.0
Port
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
Hostname
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.