dsfx/docs/hosting.md

# Hosting

This document describes how to set up and run your own DSFX server. It is
intended for users who want to run their own instance of DSFX, either for
testing or for production use. If you are looking for the DSFX client, please
see the [operating docs](./operating.md). If you are looking for the DSFX
administration docs, please see the [administration docs](./administration.md).

- [Setup](#setup)
  - [Dependencies](#dependencies)
  - [Git Setup](#git-setup)
  - [Binary Installation](#binary-installation)
  - [Running](#running)
- [Configuration](#configuration)
- [Local Files](#local-files)

---

## Setup

Due to the maturity of the project, we haven't yet created a release strategy.
We have, however, fully embraced the go ecosystem - so you can use the go
toolchain to install the project from source. This is the recommended way to
install the project, as it will always give you the latest version of the code.

### Dependencies

- [git](https://git-scm.com/)
- [golang](https://go.dev/)

In many cases, these tools are available in your system package manager. Here
are a few commands for various operating systems (not comprehensive):

- **Ubuntu**: `sudo apt-get install git golang`
- **Fedora**: `sudo dnf install git golang`
- **Arch**: `sudo pacman -S git go`
- **macOS**: `brew install git go`

If the above commands don't work for you, please refer to the official
documentation for your operating system.

### Git Setup

Currently we are hosted on **gitea cloud**, which hides everything from the
public internet by default. This means that the machine you are deploying to
will need to be able to access the gitea cloud instance. One way to do this is
to use the `.netrc` file in conjunction with a personal access token. Once you
have a personal access token, you can create a `.netrc` file in your home
directory with the following contents:

```plaintext
machine koti.casa login <your username> password <gitea personal access token>
```

Finally, you'll need to set the `GOPRIVATE` environment variable to allow go to fetch
private repositories. You can do this by running the following command:

```bash
export GOPRIVATE=koti.casa
```

If you want to persist this setting across sessions, you can add the above line to your
`~/.bashrc` or `~/.bash_profile`.

### Binary Installation

Now that you have the go toolchain set up with access to our repository, you can simply install the
project by using the `go install` command.

```bash
go install koti.casa/numenorlabs/dsfx/cmd/dsfx@main
```

### Running

If you are familiar with the go toolchain, you can run the executables in the
`cmd` directory directly. For other users, we recommend using the `go run`
command to run the project. This will automatically download and install the
dependencies for you, and run the project in a single command.

```bash
go run koti.casa/numenorlabs/dsfx/cmd/dsfx@main
```

## Configuration

The application accepts the following cli flags:

- **-h**: Show help message
- **-host**: The host on which the DSFX server will run (default: `0.0.0.0`)
- **-port**: The port on which the DSFX server will listen (default: `8000`)
- **-logLevel**: The log level to use. One of (error, warn, info, debug) (default: `info`)
- **-dataDir**: The directory where the DSFX data files are stored (default: `/etc/dsfx/data`)
- **-configDir**: The directory where the DSFX configuration files are stored (default: `/etc/dsfx/config`)

## Local Files

The DSFX server uses local files for configuration and storage. The default directories for these
files are specified in the **-configDir** and **-dataDir** cli flags. You can
change these directories by specifying the flags when you run the server.