mirror of
https://git.madhouse-project.org/algernon/iocaine.git
synced 2025-02-20 16:38:46 +01:00
f486b99984
Added a few words about compiling Iocaine, added a docker example with a TOML configuration file (vs the existing environment variable-based example), and collected a mistake describing the shape of `IOCAINE__SOURCES__MARKOV`. These together should largely address #2. Signed-off-by: Gergely Nagy <me@gergo.csillger.hu>
96 lines
4.2 KiB
Markdown
96 lines
4.2 KiB
Markdown
---
|
|
title: Configuration
|
|
description: Configuring Iocaine
|
|
weight: 1
|
|
---
|
|
|
|
`iocaine` can be configured via a TOML-format configuration file, or via the environment. Almost everything has sane defaults, but providing a wordlist, and at least one source for the markov generator is **required**.
|
|
|
|
The configuration file is split into three main sections: [`[server]`](#server), [`[sources]`](#sources), and [`[generator]`](#generator).
|
|
|
|
# `[server]`
|
|
|
|
The `[server]` section is used to configure the address and port the server will listen on, via the `bind` property. The default is shown below:
|
|
|
|
``` toml
|
|
[server]
|
|
bind = "127.0.0.1:42069"
|
|
```
|
|
|
|
This parameter is available as `IOCAINE__SERVER__BIND` when configuring via environment variables.
|
|
|
|
# `[sources]`
|
|
|
|
The `[sources]` section is the only section without defaults, specifying both options here is mandatory.
|
|
|
|
``` toml
|
|
[sources]
|
|
words = "/usr/share/dict/wamerican.txt"
|
|
markov = ["/var/lib/iocaine/markov/bee-movie.txt", "/var/lib/iocaine/markov/moby-dick.txt"]
|
|
```
|
|
|
|
The first option, `words`, refers to a word list file, with one word per line. When generating links, the *path* of the link will be a word chosen from this word list.
|
|
|
|
The second option, `markov`, is a list of files used to train the markov chain generator. These will be used to generate the main content.
|
|
|
|
These parameters are available as `IOCAINE__SOURCES__WORDS` and `IOCAINE__SOURCES__MARKOV`, respectively, when configuring via environment variables. Do note that if configuring `iocaine` this way, the `IOCAINE__SOURCES__MARKOV` environment variable *must* be a TOML list: `IOCAINE__SOURCES__MARKOV=["/var/lib/iocaine/markov/bee-movie.txt"]`.
|
|
|
|
# `[generator]`
|
|
|
|
The `[generator]` section is used to describe how garbage is generated, how many paragraphs are produced per page, how many words they may have, how many links to place, and so on. These will be discussed in the following sections about <code>[\[generator.markov\]](#generator-markov)</code>, and <code>[\[generator.links\]](#generator-links)</code>. The rest of the section looks like this:
|
|
|
|
``` toml
|
|
[generator]
|
|
initial_seed = ""
|
|
```
|
|
|
|
When configuring through environment variables, this setting is available as `IOCAINE__GENERATOR__INITIAL_SEED`.
|
|
|
|
## `[generator.markov]`
|
|
|
|
This section controls the markov generator: how many paragraphs are generated, and how many words are in each. The structure should be self explanatory:
|
|
|
|
``` toml
|
|
[generator.markov.paragraphs]
|
|
min = 1
|
|
max = 1
|
|
|
|
[generator.markov.words]
|
|
min = 10
|
|
max = 420
|
|
```
|
|
|
|
The first - `[generator.markov.paragraphs]` - sets how many paragraphs may be generated, and the latter - `[generator.markov.words]` - sets how many words each paragraph may contain.
|
|
|
|
When configuring through environment variables, these settings are available via `IOCAINE__GENERATOR__MARKOV__PARAGRAPHS__MIN`, `IOCAINE__GENERATOR__MARKOV__PARAGRAPHS_MAX`, `IOCAINE__GENERATOR__MARKOV__WORDS__MIN`, `IOCAINE__GENERATOR__MARKOV__WORDS__MAX`, respectively.
|
|
|
|
## `[generator.links]`
|
|
|
|
This section controls the link generator: the number of links, how many words are in the generated URL, and how many words are in each link's title. It looks like the following:
|
|
|
|
``` toml
|
|
[generator.links]
|
|
min = 2
|
|
max = 5
|
|
|
|
[generator.links.href_words]
|
|
min = 1
|
|
max = 2
|
|
|
|
[generator.links.title_words]
|
|
min = 4
|
|
max = 8
|
|
```
|
|
|
|
When configuring through environment variables, these settings are available via `IOCAINE__GENERATOR__LINKS__MIN`, `IOCAINE__GENERATOR__LINKS__MAX`, and `IOCAINE__GENERATOR__LINKS__HREF_WORDS__MIN`, `IOCAINE__GENERATOR__LINKS__HREF_WORDS__MAX`, `IOCAINE__GENERATOR__LINKS__TITLE_WORDS__MIN`, and `IOCAINE__GENERATOR__LINKS__TITLE_WORDS__MAX`, respectively.
|
|
|
|
# `[templates]`
|
|
|
|
```toml
|
|
[templates]
|
|
# directory =
|
|
```
|
|
|
|
The `[templates].directory` property can be set to a directory containing custom templates. If not set (the default), `iocaine` will use its own [default template](https://git.madhouse-project.org/algernon/iocaine/src/branch/main/templates/main.hbs). If configured, the directory **must** contain a `main.hbs` file, which will be used as the template for all generated pages. See the [templating](@/configuration/templating.md) documentation for more information about changing the template.
|
|
|
|
When configuring through environment variables, this setting is available via `IOCAINE__TEMPLATES__DIRECTORY`.
|