Skip to content

WriteFreely

WriteFreely is an open source platform for building a writing space on the web. There's no news feed, notifications, or unnecessary likes or claps to take you away from your train of thought. Reach outside your own site with federation via ActivityPub. WriteFreely lets anyone on Mastodon, Pleroma, or any ActivityPub-enabled service follow your blog, bookmark your posts, and share them with their followers. WriteFreely is written in Go (golang), so it runs anywhere and takes up very few resources.

License
AGPLv3
Author
Lars Frantzen
Last changed
2026-10-11

Tested with WriteFreely 0.17.2 on Uberspace 8.0.99. We can't guarantee it to work with newer versions.

Report a guide issue

Note

For this guide you should be familiar with the basic concepts of:

Prerequisites

If you want to use your own domain, set it up as described in Domains. We assume here that your username is isabell and that your domain is isabell.uber.space.

Note

In all steps, replace isabell with your username!

You'll need your MariaDB credentials:

[isabell@moondust ~]$ my_print_defaults client
--default-character-set=utf8mb4
--user=isabell
--password=MySuperSecretPassword

Installation

Database Setup

Create a new database: 

[isabell@moondust ~]$ mariadb -e "CREATE DATABASE ${USER}_writefreely CHARACTER SET latin1 COLLATE latin1_swedish_ci;"

Download

Use wget to download v0.17.2:

[isabell@moondust ~]$ wget https://github.com/writefreely/writefreely/releases/download/v0.17.2/writefreely_0.17.2_linux_amd64.tar.gz
[isabell@moondust ~]$ tar xzf writefreely_0.17.2_linux_amd64.tar.gz

Configuration

Interactive Configuration

Change to the writefreely directory and start the interactive configuration process:

[isabell@moondust ~]$ cd writefreely
[isabell@moondust writefreely]$ ./writefreely config start

The Server setup: - For Environment choose Production, behind reverse proxy - For Local port keep 8080

The Database setup: - For Database driver choose MySQL - For Username and Password use the MariaDB credentials (see above) - For Database name use isabell_writefreely - For Host keep localhost - For Port keep 3306

The App Setup: - Choose the options to your liking, for Public Url either use the domain you assigned to the Asteroid, or https://isabell.uber.space

Create Admin User for Multi-User Instances

If you chose Multi-user instance you need to create a WriteFreely admin user via: 

[isabell@moondust writefreely]$ ./writefreely user create --admin <name>:<password>
Replace <name> and <password> with the WriteFreely admin credentials you want to use, and note that <name> cannot be admin.

Generate Encryption Keys

Generate the encryption keys for your instance: 

[isabell@moondust writefreely]$ ./writefreely keys generate

Correct bind Entry

With a text editor change the bind entry in ~/writefreely/config.ini as follows: 

[server]
...
bind                 = 0.0.0.0
...

Configure Web Backend

To make the application accessible from the outside, configure a web backend: 

[isabell@moondust ~]$ uberspace web backend add / port 8080 --force
OK: Added webbackend '/' to your Asteroid

Add Service

Create this file: ~/.config/systemd/user/writefreely.service with this content: 

[Install]
WantedBy=default.target

[Service]
WorkingDirectory=/home/isabell/writefreely
ExecStart=/home/isabell/writefreely/writefreely
Restart=always
RestartSec=10

Start the service: 

[isabell@moondust ~]$ systemctl --user enable --now writefreely.service

Start Writing

Now you should be able to access your WriteFreely instance under https://isabell.uber.space. Log in with the username and password provided during configuration.

Debugging

Did you always replace isabell with your actual username? Also check if the service is running: 

[isabell@moondust ~]$ uberspace service list

  Service       Status   Enabled
 ─────────────────────────────────
  writefreely   active   disabled
If the writefreely service is not active, check the steps where you added the service.

Media

WriteFreely does not provide a way to manage media (like adding pictures to your blog posts). You can either rely on an external service, or use your Asteroid also as a simple file server.

Note

All files you provide this way are accessible from anywhere via their URL.

A simple setup would look like this:

[isabell@moondust ~]$ mkdir ~/www/html/assets
[isabell@moondust ~]$ uberspace web backend add /assets apache

Now you can store files under ~/www/html/assets and access them via their URL. For instance, if you store a pic.png under ~/www/html/assets/blog1/post1/pic.png you can show this file in your blog post via:

![Alt text](https://isabell.uber.space/assets/blog1/post1/pic.png)

Migrating your blog stays simple, just zip the assets folder and move it to a new server.

Updates

Note

The Admin Dashboard has a tab Updates where you can check if you are up to date. Also, check the update feed regularly.

For each version, there are upgrade instructions given in their release notes.