docs/admin/config.md

Configuring WriteFreely

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
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)

Database

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

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
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

OAuth

There are several possible OAuth configuration blocks for different implementations.

Generic OAuth

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