WriteFreely is configured through an `.ini` file. By default, WriteFreely will look for the configuration file `config.ini` in the current directory. However, you can supply a different file or location by running WriteFreely with the `-c [filename]` flag, for example:
```
writefreely -c /var/lib/writefreely/config.ini
```
## Server
The following fields are valid in the `[server]` section of your configuration file. They affect how the application runs.
| Field | Description | Default |
| ----- | ----------- | ------- |
| `port` | Port for the application to serve HTTP requests on | _None_ |
| `bind` | Address to bind the application to | localhost |
| `tls_cert_path` | TLS certificate path. If supplied with `tls_key_path`, requests will be served on port 443. If `autocert` is `true`, certificates and keys will be stored in the given directory. | _None_ |
| `autocert` | Enable automatic certificate generation with Let's Encrypt. Requires `tls_cert_path` and `tls_key_path` to not be empty, and running in standalone server mode, i.e. `port` set to `443`. | `false` |
These fields only apply to instances using **SQLite**.
| Field | Description | Default |
| ----- | ----------- | ------- |
| `filename` | Database file | _None_ |
## App
The following fields are valid in the `[app]` section of your configuration file. They affect how the application functions, especially in user-facing ways.
| Field | Description | Example value |
| ----- | ----------- | ------- |
| `site_name` | Name of the website, publicly shown in several places | Our Community |
| `site_description` | Site description, shown in NodeInfo | A place to write freely. |
| `host` | Full hostname (including scheme) users will see | https://pencil.writefree.ly |
| `notes_only` | By default, WriteFreely federates posts as [`Article`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-article)s and [`Note`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-note)s. This only sends them as `Note`s. | false |
| `disable_password_auth` | Whether or not new users can sign up via the landing page. Useful if you want to limit new users to your OAuth provider. | false |
| `max_blogs` | Maximum number of blogs a single user can create under one account | 5 |
| `local_timeline` | Whether or not the instance reader (and the _Public_ option on blogs) is enabled | true |
| `user_invites` | Who is allowed to send user invites, if anyone. A blank value disables invites for all users. Valid choices: _empty_, `user`, or `admin` | user |
| `default_visibility` | The default visibility setting for newly-created blogs. Valid choices: `unlisted` (default), `public`, or `private` | public |
These fields are experimental and subject to change with little notice. _Using these? Let us know so we can make them a permanent part of WriteFreely!_
| Field | Description | Example value |
| ----- | ----------- | ------- |
| `forest` | When enabled, certain unimportant details ("trees") are hidden from admin view, such as the Application Monitor. Meant for managed hosting environments. | false |
| `chorus` | Indicates this instance is optimized for everyone's collective voice, rather than individuals. Meant for writing groups, company instances, etc. See Chorus docs for more info. | false |
Configure the `[email]` section to enable password resets and other email-based functionality. Today, WriteFreely only supports [Mailgun](https://mailgun.com) as a sending provider.
With both configuration values set, your instance will have the following email-based functionality automatically enabled:
* **Forgot Password functionality**. Users will find a link on the _login_ page that allows them to reset their password via email.
* **Email subscriptions / newsletters**. Blog authors can optionally let readers subscribe to their blog posts via email, and optionally supply an email address where readers can privately reply. Authors will also have access to their subscribers list.
The following fields are valid in the `[oauth.generic]` section of your configuration file, which is for the most general OAuth setup that should work with many spec-compliant OAuth providers.
| `client_id` | The client ID, or client key, associated with WriteFreely in the OAuth provider application. | _(a long string of characters)_ |
| `client_secret` | The client secret associated with WriteFreely in the OAuth provider application. | _(a long string of characters)_ |
| `host` | The base url of the OAuth provider application, including the protocol. | https://example.com |
| `display_name` | The human-readable name of the OAuth service that appears on the login button, will appear as "Log in with [display_name]". | _(name of the application)_ |
| `callback_proxy` | The url of an inbound proxy that sits in front of the default `/oauth/callback/generic` endpoint. Use if you want the OAuth callback to be somewhere other than that generic location. Default is blank.| https://example.com/whatever/path |
| `callback_proxy_api` | The url of an outbound proxy to send your OAuth requests through. Default is blank. | https://my-proxy.example.com |
| `token_endpoint` | The API endpoint of the OAuth provider implementation to obtain an access token by presenting an authorization grant or refresh token. This is a fragment of a url, appended to `host` as described above. | /oauth/token |
| `inspect_endpoint` | The API endpoint of the OAuth provider that returns basic user info given their authentication information. This is a fragment of a url, appended to `host` as described above. | /oauth/userinfo |
| `auth_endpoint` | The API endpoint of the OAuth provider that returns an authorization grant. This is a fragment of a url, appended to `host` as described above. | public |
| `scope` | A scope or set of scopes required by some OAuth providers. This will usually be blank in this config file, and is set to "read_user" by default. | read_user |
| `allow_disconnect` | Whether or not an individual user is allowed to disconnect this OAuth provider from their account. | false |
