The Preface That Cost Me A Whole Day And Night

I couldn’t sleep in the middle of the night yesterday. Actually, that’s not quite it – my “tinkering” itch flared up again. There are tons of forum veterans in the group, and I wanted to try setting up a forum too (can’t let my server go to waste). This post also records the pitfalls I hit and my thought process:

1. Choose Docker Or Direct Framework Setup?

My intuition told me I had to use Docker. Compared with directly using LNMP and other stacks, Docker uses less memory and is much quicker to set up.

If you insist on deploying everything step by step… fine, I’ll put that down here. Refer to the official docs: Installation | Flarum Documentation

2. Setting Up Flarum With Docker

At first I chose the Flarum image from the Docker app store, but damn, I found that I couldn’t set the account and password. Plus, the database for the Docker-deployed project lives in a “virtual space” with no obvious way to manage it in aaPanel (maybe I’m just too noob), so I switched to using docker-compose to pull and configure everything.

2-1 Create Image Files

Put docker-compose.yml in whatever folder you like. For example, I chose the site directory: /www/wwwroot/bbs/docker-compose.yml

You’ll also need flarum.env.

Then write the contents of docker-compose.yml (edit with vi, i to enter insert mode, esc to exit insert mode, :wq to save and quit).

2-2 Pull The Image

Then bind a website domain name to the container and add SSL.

2-3 Updating Flarum

I ended up updating by accident, because when I was pulling a plugin, I used -W, which directly upgraded me to the latest version 1.8.x.

3. Operations You Need To Do In Flarum

Let’s first get inside the container before we do anything: For example, in aaPanel:

Then go to Flarum’s directory:

You can also directly:

3-1 Add Chinese Language Support

3-2 Install Extensions

3-3 Uninstall Extensions

3-4 Clear Cache

3-5 Enable Debug Mode

There is a config.php file in the app directory:

Then just edit it:

Change debug from false to true.

4. Problems Encountered

4-1 Unable To Write Files

Unable to write files. Please check file permissions, try again, or run the command directly from the command line.

Possible cause:

Check whether there is a lock file in the storage/cache directory:

Obviously a lock file appeared under the root user:

4-2 Unable To Connect To The Deployed Sonic

I used a Sonic project deployed with Docker to add Chinese search support.

Concrete steps: \ The following error occurred:

It’s probably a Docker network connectivity issue: \ You can fix it by creating a network:

Add Sonic to it:

Put Flarum into the same network as well (my Flarum container is called flarum):

Change the Sonic address in Flarum’s config:

Run again:

4-3 Common JS Issues When Updating Extensions

This indicates that when Flarum is loading data, the API data returned by the backend doesn’t match what it expects. This usually happens when:

1. After an extension update, the API schema changes but the frontend JS is still the old version, so Store.pushPayload gets JSON data that’s missing the type field.
2. Cache issues: the frontend is still loading old JS files that don’t match the new backend.
3. Extension bugs or conflicts: some extension returns invalid JSON (for example, null or an incomplete structure).
4. Missing database fields / migrations not run: after upgrading an extension you need to run php flarum migrate, otherwise the response data format will be broken.