Pushing Electrons

I've had blogs in various forms for ...a long time now, but struggled to use them effectively due to various technology challenges and life events. With the growth of the Fediverse and the wonderful technology stacks connected to it, it felt like time for a change. I decided to go with a WriteFreely instance for a few reasons:

• ActivityPub compliance means that creating, saving, and sharing posts is easy and well-supported both individually and in the Fediverse.
• WriteFreely has a clean, simple interface that works well on both desktop and mobile (with the mobile part becoming increasingly important!)
• WriteFreely is free, open-source software (FOSS) with great documentation and support.

While the process was pretty well-documented and gotchas were few relative to other technologies, there were still enough trip hazards to keep things, um, interesting. This post is intended to provide a more complete process than is shown in the official documentation, and hopefully save people some time and headaches in the future.

The guide is targeted toward people with some experience using the command line on computers, especially on computers running Linux. If this isn't you, check out Write.as for a great instance that's already fully set up and supported. If you still want your own instance, reach out to me at @dulanyw@techhub.social.

Disclaimer

I am not a sys admin or professional website setter-upper – my tools are an engineering background, search engine, and patience. I've gotten websites to work well on many occasions, but I can't guarantee that everything below is best practice. (If you have advice on best practices I should include here – please let me know @dulanyw@techhub.social!)

This guide is also targeted toward small individual instances. This means: 1 user, low-to-medium volume of posts (a handful a day), generally low traffic with occasional peaks. Changes from this (multiple users, lots of posts/day, higher traffic) are very solvable with a dedicated high-performance database like PostGRES, use of Apache or nginx for serving requests, and/or more resources allocated to the server. These are great, but out of scope for now. The focus of this guide is “simple and low cost”, which means we will be doing as little as possible, as cheaply as possible to get the system up and running.

I should also note that these instructions are good as of December 2022. Major changes to WriteFreely or Ubuntu/Debian systems may change specific commands/processes, although the spirit would likely be the same.

Requirements

You will need the following to get started:

• A server. A great option is a cloud-based server with a dedicated IP from a provider like DigitalOcean or Kamatera. These providers will also let you dynamically adjust resources to fit your needs and budget, which is helpful if you want to implement a more demanding system in the future.
• A domain name. Again, a lot of providers here – I've had good experience with Ionos. You can also get free domains from Freenom. With whatever provide you choose, the key here is the ability to manually update your DNS records with that provider.
• Some way to capture information through the process, such as IP address and login information. A notepad (real or virtual) will work, although a password manager (such as Keepass) would be better.

Per the WriteFreely Official Documentation, you will need also need:

• Admin rights to the server (which you should already have if you use a cloud-based server approach)
• About 30 minutes.

We'll get this blog up and running in four quick phases:

1. Prep work
2. Installation
3. Configuration
4. Clean-up

Prep Work

1. First, set up your server. I recommend using either an Ubuntu or Debian software image (latest versions) for ease of use. For a small instance, aim for minimum resource requirements (1GB RAM, 10GB hard drive, etc.). Select a password you can keep safe (and find easily!). Once the server has been set up, get the IP address.

2. Next, you'll need to make sure your domain name points to your server. That way, when people type in your blog's address (like https://www.awesomeblog.com), they get taken straight to your WriteFreely instance. In your domain registrar's interface, make sure the “A” record is updated with the IP address you were given in Step 1, then save it. It will take a few hours for your provider to share this with the rest of the Internet – by which point your blog should be up and running!

3. Time to connect to your server. Open a terminal (Linux) or command prompt (Windows) and type ssh root@<ip address> (substituting your own server's IP address from Step 1 for – for example ssh root@1.2.3.4). When it asks for your password, either enter it manually or copy and paste it (pasting into the terminal requires ctrl+shift+V instead of the normal ctrl+V), then press Enter. If all goes well, you should be logged in as root.

4. Next, we add a non-root user who can install things, and complete the remaining steps as that user. (It's bad practice to do everything as root user.) On the command line, enter adduser <username>, where is the name of the new user. (For example, enter adduser johnny.) Follow the prompts to add a password for this user and update their information, entering Y when the computer asks “Is this information correct? [Y/n]“.

5. With this complete, enter the command sudo usermod -aG sudo <username>, again entering the name of the new user instead of . If prompted, enter the root password to complete this. This raises the privileges for the new user so that they can install software.

6. Finally, type su <username> (replacing with the name of the new user). Enter the new user's password if requested.

7. Run the command sudo apt-get update && sudo apt-get dist-upgrade -y to make sure your system has the latest software.

Installation

Now, it's time to start setting up WriteFreely.

1. First, let's make a place on your system for the site. Create a couple of folders with the commands: sudo mkdir /var/www && sudo mkdir /var/www/mysite, then move into the folder with the command cd /var/www/mysite/. (You can use a different name than “mysite” – best practice is to keep it lowercase and without spaces.)

2. Now, download the latest version of the software. You can find it by going to the WriteFreely Github page in your browser, then scrolling to the bottom to find the asset that ends in “.tar.gz”. Right-click on the link and select “copy link”. Then, in your terminal, type sudo wget <link>, doing a ctrl+shift+v paste for the link in place of . For example, the command as of this writing would be sudo wget https://github.com/writefreely/writefreely/releases/download/v0.13.2/writefreely_0.13.2_linux_amd64.tar.gz. After this is run, make sure the download was successful with the command ls -l, which should show you the name of the file with a file size greater than 0 (hopefully a big number immediately to the left of the date).

3. Unzip the file with the command sudo tar -xvf <filename>, where is the name of the file you just downloaded. You should be able to just enter the first few letters of the file, then press the “tab” button to autocomplete, which will save a lot of typing and headaches.

4. Delete the original file using sudo rm <filename>. Again, use autocomplete to write out the full filename for you. This step isn't strictly required, but is good housekeeping practice.

5. With all of the files in place, time to start the configuration! Don't worry – WriteFreely has an interactive configurator that makes this part a lot easier. Enter cd writefreely && sudo ./writefreely config start to enter the writefreely folder and start the configurator. For each prompt, you can use the arrow keys to select your choice. If there is an error during the process, it will kick you out of the configurator, and you can retry with the command sudo ./writefreely config start. For the implementation described above (production, small instance, single user), make the following choices at each prompt:

   • Production, standalone
   • Secure (port 443), auto certificate
   • SQLite
   • Accept the default database name by pressing Enter
   • Single user blog
   • Choose an admin user name. You won't be able to change this later for logging in to the site, although you will be able to change the alias you use for federation.
   • Choose an admin password. You can change this later if needed.
   • Choose the name of the blog. You can change this later if needed.
   • For public URL, type the domain name from Step 2, being careful to start it with https:// (such as https://www.awesomeblog.com).
   • Federation: Enabled
   • Choose “Public” or “Private” stats according to your preference.
   • For instance metadata privacy, make the selection according to your preference.

Configuration

We're halfway done with the configuration.

1. Next, generate the encryption keys by typing sudo ./writefreely keys generate in the terminal, then press “Enter”.

2. Set up the database by typing sudo ./writefreely --init-db in the terminal, then press “Enter”.

3. Next step is to set up the certificate for secure communication. We'll use the LetsEncrypt Certbot for this. Use the following commands:

   • sudo apt install snapd -y to install the Snap package manager.
   • sudo snap install core; sudo snap refresh core to ensure the latest version is installed.
   • sudo snap install --classic certbot to install Certbot.
   • sudo ln -s /snap/bin/certbot /usr/bin/certbot to make sure Certbot can be run.
   • sudo certbot certonly --standalone to run Certbot. Enter your email address when prompted. Press “Y” when prompted to agree to the terms of service. Select “Y” or “N” regarding joining the EFF mailing list. Enter the domain name for your site (from Step 2) when prompted without the leading “https://” (for example, enter “awesomesite.com” without the quotes).
   • After the certificate is issued, save the locations of the certificate and private key to your notepad – we will need them for the next step. They should look something like “/etc/letsencrypt/live/mysite/fullchain.pem” and “/etc/letsencrypt/live/mysite/privkey.pem”. Use Ctrl+Shift+V to copy from the command line.

4. Type sudo vim config.ini to open the config file in Vim, then press “i” to enter editing mode. Update the following entries:

   • bind = 0.0.0.0
   • tls_cert_path = – set this to the address for the “fullchain.pem” file from the previous step.
   • tls_key_path = – set this to the address for the “privkey.pem” file from the previous step.
   • autocert = false
   • site_description = – enter a description for your site. You can change this later, if you'd like.

5. Press the Escape button on your keyboard, type :wq, then press “Enter”. This saves the file, then closes the Vim text editor.

6. With that, we're ready to test it out! WriteFreely comes with its own built-in server software, so you just have to enter sudo ./writefreely in the terminal, then press “Enter” to launch your site. Go to the URL for your website (or the IP address if the URL doesn't work – DNS may still be updating!), and you should see a default webpage. Congrats!

Clean-up

Now that we know everything works, we just have to make it work for the long-haul. This means setting WriteFreely up as a service in your system, which means it is constantly, automatically running on your system.

Type sudo vim /etc/systemd/system/writefreely.service, press “i”, then copy/paste the following text:

[Unit] Description=WriteFreely Instance After=syslog.target network.target

[Service] Type=simple StandardOutput=syslog StandardError=syslog WorkingDirectory=/var/www/mysite/writefreely ExecStart=/var/www/mysite/writefreely/writefreely Restart=always

[Install] WantedBy=multi-user.target

(If you named your folders something other than “mysite”, be sure to update those lines appropriately!)

As before, press the Escape key, then type :wq in the terminal, and press “Enter”. This will save the file and exit Vim.

Finally (finally!), type sudo systemctl start writefreely in the terminal and press “Enter” to start the service. You can see what's going on with the server using the command journalctl -f -u writefreely.service.

Conclusion

Congratulations! You now have your own personal instance of WriteFreely! You can now blog and federate to your heart's content without being dependent on a big social media platform. Doesn't that feel good?

Big shout-out to the WriteFreely team for the wonderful project and great starting guide. Thanks to Priyanka Saggu for writing this guide, offering very helpful information in a similar vein. Also, here are the WriteFreely admin commands and configuration guide if you ever need them in the future.

Tags: #fediverse #writefreely #how-to

Written by Dulany Weaver. Copyright 2022-2024. All rights reserved.