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
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 |
tls_key_path |
TLS private key path. If supplied with tls_cert_path, requests will be served on port 443. |
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 |
gopher_port |
Port to run Gopher server on. If this is 0, Gopher access will be disabled. |
0 |
templates_parent_dir |
The parent directory containing the templates directory |
(current directory) |
static_parent_dir |
The parent directory containing the static directory |
(current directory) |
pages_parent_dir |
The parent directory containing the pages directory |
(current directory) |
keys_parent_dir |
The parent directory containing the keys directory |
(current directory) |
The following fields are valid in the [database] section of your configuration file. They affect how the application stores and retrieves data.
| Field | Description | Default |
|---|---|---|
type |
Database driver type. Valid choices: mysql or sqlite3 |
None |
These fields only apply to instances using MySQL.
| Field | Description | Default |
|---|---|---|
username |
Database username | None |
password |
Database password | None |
database |
Database name | None |
host |
Database hostname to connect to | localhost |
port |
Database host port to connect to | 3306 |
tls |
Whether or not to use TLS to connect to database | false |
These fields only apply to instances using SQLite.
| Field | Description | Default |
|---|---|---|
filename |
Database file | None |
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 |
editor |
The editor template file all users will use. Default: pad, other options: bare, classic. |
classic |
single_user |
Whether or not the instance is for one blog | false |
min_username_len |
Minimum required length of usernames | 3 |
federation |
Whether or not federation via ActivityPub is enabled | true |
notes_only |
By default, WriteFreely federates posts as Articles and Notes. This only sends them as Notes. |
false |
public_stats |
Whether or not usage stats are made public via NodeInfo | true |
monetization |
Enables monetization options for users (currently, only Web Monetization) | true |
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 |
wf_modesty |
When enabled, this removes much of the WriteFreely branding and explanatory text | false |
These fields can always be set, but only apply to multi-user instances.
| Field | Description | Example value |
|---|---|---|
private |
When enabled, all blogs and posts will only be readable by other authenticated users on the instance. | false |
landing |
The default landing route for an unauthenticated user | /login |
open_registration |
Whether or not anyone can register via the landing page | true |
open_deletion |
Whether or not users can delete their account on their own (via web UI) | true |
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 |
There are several possible OAuth configuration blocks for different implementations.
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.
| Field | Description | Example value |
|---|---|---|
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 |
map_user_id |
Use this User ID key in the provider's user info, instead of the default key (user_id) |
user_id |
map_username |
Use this Username key in the provider's user info, instead of the default key (username) |
username |
map_display_name |
Use this Display Name key in the provider's user info, instead of the default key (none) | name |
map_email |
Use this Email key in the provider's user info, instead of the default key (email) |
email |