Configuring WriteFreely — WriteFreely Documentation

Configuring WriteFreely — WriteFreely Documentation
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
, Gopher access will be disabled.
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
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
federation
Whether or not federation via ActivityPub is enabled
true
notes_only
By default, WriteFreely federates posts as
Article
s and
Note
s. This only sends them as
Note
s.
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
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
Email
Configure the
[email]
section to enable password resets and other email-based functionality. With a provider fully configured, your instance will have the following email-based functionality automatically enabled:
Forgot Password functionality
. Users will find a link on the
page that allows them to reset their password via email.
Email subscriptions / newsletters
. Blog authors can 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.
WriteFreely supports configuring either a generic bulk email sender via SMTP, or
Mailgun
For all providers, you'll set the following value:
Field
Description
Example value
domain
Domain where all of your messages will originate (can be different from web domain)
writeasletters.com
Next, supply additional configuration values depending on your bulk email provider.
SMTP
Configure these values to send via SMTP and use any provider you'd like.
Field
Description
Example value
smtp_host
SMTP provider hostname
example.com
smtp_port
SMTP provider port number
587
smtp_username
SMTP provider username
username
smtp_password
SMTP provider password
password
smtp_enable_start_tls
Whether to use STARTTLS
true
Mailgun
Supply these values to use Mailgun as your sending provider.
Field
Description
Example value
mailgun_private
Mailgun private key
key-...
mailgun_europe
Whether to use European Mailgun servers
true
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.
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.
callback_proxy_api
The url of an outbound proxy to send your OAuth requests through. Default is blank.
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