Add installation and usage details to README

This commit is contained in:
Jansen Price 2020-09-28 14:06:12 -05:00
parent 151299ea06
commit ec7a27af1d
2 changed files with 219 additions and 3 deletions

220
README.md
View File

@ -1,3 +1,219 @@
# orbit
# 🛰️ Orbit
Server for gemini protocol written in PHP
Server for gemini protocol written in PHP
## Dependencies
- PHP 7.x or higher
- composer (getcomposer.org)
## 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-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`
## 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.

View File

@ -17,7 +17,7 @@ class Server
{
const SCHEME = "gemini";
public static $version = "0.4";
public static $version = "0.5";
public $config;
public $cert;