# Fs

(*Note*: If you are reading this on Github, you can find the
original Fossil repository [here](https://www.bloovis.com/fossil/home/marka/fossils/fs/home)).

Fs is a simple static file server for HTTP and HTTPS.

## Prerequisites

Fs requires the C library for yaml.  it can be installed on Debian
or Ubuntu using:

    sudo apt install libyaml-dev

## Build

To clone this repository:

```
fossil clone https://www.bloovis.com/fossil/home/marka/fossils/fs
```

To build Fs, use this:

    shards install
    crystal build src/fs.cr

This will create a binary `fs` in the current directory.  This executable
file and the configuration file (see the next section) are all that
you need for an fs installation.

## Configuration

Fs keeps its configuration information in a YAML file.  To create
an initial configuration, copy the file `fs.yml.sample` to `fs.yml` and edit as needed.
The configuration file contains these required fields:

* `root` - the root directory of the files to be served (e.g., `/var/www/html`).
* `host` - the hostname that fs should bind to.  Use `127.0.0.1` for localhost,
or `0.0.0.0` for all hosts.
* `port` - the number of the port to be used by the Fs server.  The recommended
value is 8083, to avoid conflict other popular servers.

The configuration file contains these optional fields:

* `sslport` - the number of the port to by used by the Fs server for SSL (https) access.
This option is unnecessary if you are running Fs behind an Apache reverse proxy
and Apache has been configured for SSL.  If you do set this option, you must
also set `key` and `cert`.
* `key` - the pathname of the file containing the SSL key.  For example,
if you obtained your key from Let's Encrypt, the pathname
might be something like `/etc/letsencrypt/live/www.example.com/privkey.pem`.
* `cert` - the pathname of the file containing the SSL certificate.  For example,
if you obtained your certificate from Let's Encrypt, the pathname
might be something like `/etc/letsencrypt/live/www.example.com/fullchain.pem`.
* `log` - the pathname of the log file.  Fs will create the file if it does not
  exist; otherwise, it will append log messages to the end of the file.  If this field
  is not present, Fs will send log messages to stdout.
* `loglevel` - the logging level, corresponding to the values of `Logger::Severity `:
    - debug
    - error
    - fatal
    - info
    - unknown
    - warn

## Running

To run Fs as a server, use this:

    ./fs [config-option]

The server will run until terminated by a Control-C or other signal.

Fs supports a single option: `--config=FILENAME`, which you can use
to specify to the path to the configuration YAML file.  The default
value is `./fs.yml`.

## System Service

It is more convenient to start the Fs server as a system service than to run it
from the command line.  To do this, copy the file `fs.service.sample` to `/etc/systemd/system/fs.service`
and edit it as necessary.  The values most likely to need editing are `WorkingDirectory`
and `ExecStart`.

Start the fs service and check its status:

    systemctl daemon-reload
    systemctl enable fs
    systemctl start fs
    systemctl status fs
