Fiora Build Guide

Preface#

To fulfill one of my early wishes of studying computer science — a chat room, I am here to build Fiora again. I have built Fiora multiple times before, but only once successfully, and that was because I used Docker for installation, utilizing an image file, so it cannot be considered a true build success. The build guide I am writing this time refers to building from source code.

Fiora#

A chat room system developed by Suisui-jiang. For various reasons, Fiora is no longer updated and has little maintenance, so wanting to run Fiora again in 2023 is a very difficult problem. Additionally, the Fiora docs are not detailed enough, making it easy for newcomers to stumble. Setting aside the lack of maintenance and difficulty in building, Fiora itself is actually an excellent chat room system.

Pitfall Guide#

If you have a general grasp of Fiora's build mechanism but encounter some insurmountable issues, here are some pointers for you.

1. Node.js version issue, please use v14 LTS version
  If you encounter issues similar to the image below when running yarn build:web, which is when building the client

This is likely due to your Node.js version being too high, as this is a project that started in 2015, and using a high version of Node.js today is inappropriate. In the 6th line from the bottom of the image, you can see the current Node.js version you are using. If you cannot find it, you can execute the command

# Check Node.js version
node -v
# or
node --version

to check the version of Node.js you are using.

It is usually the latest version, but you should use Node.js v14. After switching, run the above command again to check if it takes effect. If it does not, try restarting the server, and after switching, you need to reinstall yarn, install dependencies, and build the client.

1. Building the client takes too long, please upgrade the server, recommended 2 cores 2GB RAM
1. Obtaining UserID, you cannot get the UserID using Fiora's built-in commands, please check the console
1. Issues with building the accompanying App for Fiora, you need to use a new build method, rather than the method described in Fiora docs. However, please note that due to a code refactor some time ago, the App may no longer be able to communicate with the server.

Start Building#

Server Configuration Guide#

Although Fiora has low configuration requirements, it is not without its thresholds, as it involves building from source code, so certain configurations are needed.

Configuration requirements: 1 core 2GB or higher (recommended 2 cores 2GB)
Network requirements: must be able to connect to the internet
Disk size: above 2GB
Environment requirements: Node.js (version v14), MongoDB, Redis
Server system: Ubuntu22 (this system is used to describe the build guide)

I will not describe how to install Node.js, MongoDB, and Redis. If you want to save trouble, you can install our old friend BT.CN and choose to install the PM2 manager, so you won't need to install pm2 or npm separately.

Build Guide#

Web Client Build#

First, we need to clone the project to the local machine. Before doing this, please ensure your server has git functionality, which is usually the case. Enter the following command

# Clone the project to local
git clone https://github.com/yinxin630/fiora.git -b master

It is worth noting that if your server is located in China, the clone may fail. You can choose to download it from GitHub and then upload it to the server. After cloning, you need to enter the Fiora directory.

cd /fiora

When executing this code, be sure to include the directory you are currently in. Assuming I cloned Fiora into the directory /www/project, the command I need to enter should be

cd /www/project/fiora

Next, we must confirm whether the Node.js version being used is v14. Please enter the following command to check.

# Check Node.js version
node -v
# or
node --version

This is crucial for the yarn you installed and the success of subsequent builds. If it is not v14, please switch to v14.

After this, we need to confirm whether yarn is installed, it usually is not. If you believe you have installed it, you can enter the following command to confirm.

yarn -v

If you are sure you do not have yarn, you need to enter the following command to install it.

npm install -g yarn

After a short wait, yarn will be installed. Generally, there are no specific requirements for yarn. If you are sure there are issues, you can try switching to version 1.22.19, which has been tested to build normally.

23/12/23 Supplement: Resolved a series of issues, supported Fiora's built-in command line tool.

Install the dependencies required for the project

yarn install

Then link the Fiora project

yarn link "fiora"

Now we are ready to officially build Fiora. Building Fiora is actually quite simple; once the above work is completed, you can enter the command

yarn build:web

to build Fiora. After waiting for a while, we will have completed the build.

Next, configure JwtSecret. Although I do not know why this step is necessary, it cannot run without it. Enter the following command in the command line

echo "JwtSecret=<string>" > .env2

Replace <string> with a secret text.

Finally, you can start Fiora

yarn start

After starting, open the browser and go to http://[ip address]:[port] (for example, http://127.0.0.1:9200) to access the website. The default port is 9200.

Adding an Administrator#

This section uses Fiora's built-in script. If it cannot be executed, please check if you have linked the Fiora project.

yarn link "fiora"

Generally speaking, if you follow the above build steps, you do not need to check and can add an administrator.

For more Fiora built-in scripts, see → Scripts | Fiora Docs

After successfully starting Fiora, you will enter Fiora's running log. Let's go to the address where it started successfully, register a user, and remember the username. Press CTRL and C on your keyboard to exit the running log.

fiora getUserId [username]

The [username] part is the username of the registered user, and you can obtain the UserID through this method.

658637b993f5dbef4c3e1f0a is the UserID we need, and we need to add this ID to line 34 of /packages/config/server.ts

administrator: env.Administrator ? env.Administrator.split(',') : ["658637b993f5dbef4c3e1f0a"],

After completing the configuration, restart Fiora.

Unresolved Issues#

App Build#

After reviewing a lot of materials, I found that the build method provided by Fiora App | Fiora Docs is completely impossible to build successfully in 2023, and it will definitely report a lot of errors! Moreover, after I successfully built the App, I found that due to a code refactor some time ago, the App can no longer communicate with its server in 2023!!!! Even Suisui-jiang's own App cannot do it. The reason I am writing about the App build here is that if any kind-hearted expert sees this, they can help solve this problem!!

When completing the Web build, there will be an app directory in the /fiora/packages directory. Enter it, as this is the directory we will focus on for building the App.

cd /fiora/packages/app

Enter the following command in the command line to install the latest EAS CLI

npm install -g eas-cli

Then go to Expo to register an account and remember the username and password, as we will be using cloud builds for the App, not local builds. Next, log in to your account

eas login

Enter the username and password you just registered to complete the verification. Then enter the following command in the command line, choose the type of package you want to build, and use ↑, ↓, ENTER (return key) to select. I will only choose Android here.

eas build:configure

Next, enter the following command to perform the first build

eas build --platform android

After waiting for about 10 minutes, you will see the following content on the homepage of Expo after logging in.

Click in to download your .aab format installation package, yes, it is .aab and not .apk, so we need to build a second time. Before the second build, we need to go to the /fiora/packages/app directory and edit a file named eas.json, replacing its content with

{
  "build": {
    "preview": {
      "android": {
        "buildType": "apk"
      }
    },
    "preview2": {
      "android": {
        "gradleCommand": ":app:assembleRelease"
      }
    },
    "preview3": {
      "developmentClient": true
    },
    "production": {}
  }
}

Then we will package and build again, but this time we will use the following command, which is different from what was written above.

eas build -p android --profile preview

After waiting another 10 minutes, the App build will be completed, and you can download the .apk format installation package, which even automatically signs it for you.

But as I said, this App cannot communicate with the server, and I need the help of experts!!

Port Issues#

Some service providers have strict firewall policies, so we must open the required ports. The ports required by Fiora include but are not limited to

19002 needed for building the App
6379 needed for building the App
9200 Fiora Web port, customizable
27017 database port

Other Issues#

Configuration file: Configuration | Fiora Docs
Custom domain name: Reverse Proxy | Fiora Docs

Modification Content#

If you want to make certain modifications to your Fiora, you must check this part. As mentioned before, due to a code refactor some time ago, Fiora | Docs is no longer as applicable in 2023, and the directory structure it provides is no longer valuable. Therefore, if you want to modify Fiora's source code, you must check the directory structure I have written.

# Fiora partial directory structure
|-- [.github]                // github actions
|-- [.vscode]                 // vscode workspace configuration
|-- [packages]                // directory for all source code storage
|------  [app]                // App source code
|----------  [src]            // App source code
|--------------  [pages]      // App front-end UI
|----------  [app.json]       // basic information for packaging the App
|----------  [src]            // App source code
|------  [assets]             // static resources
|------  [config]             // Fiora configuration folder
|----------  [client.ts]      // client configuration
|----------  [server.ts]      // server configuration
|------  [database]           // database methods, generally do not modify
|------  [server]             // Web stored after build completion
|------  [utils]              // utils
|------  [web]                // Web source code
|----------  [src]            // Web source code
|--------------  [modules]    // Web front-end UI
|-- .eslintignore             // eslint ignore
|-- .eslintrc                 // eslint configuration
|-- .gitignore                // git ignore
|-- Dockerfile                // docker file
|-- LICENSE                   // fiora license
|-- docker-compose.yaml       // docker compose configuration
|-- package.json              // npm
|-- tsconfig.json             // typescript configuration
|-- yarn.lock                 // yarn
...

Conclusion#

These are all the experiences I went through while building Fiora this time. I hope to help future builders avoid some pitfalls or teach newcomers how to build the Fiora chat room. This article may still have some incomplete parts, and I hope for your understanding. If there are any issues, please point them out, and I will make improvements. Additionally, if any experts have a way to solve the problem of the App not being able to communicate with the server, please send it to my email [email protected], I would be very grateful!

References#

Fiora Docs: https://yinxin630.github.io/fiora/zh-Hans/

Create your first build: https://docs.expo.dev/build/setup/

Expo CLI: https://docs.expo.dev/more/expo-cli/#installation

Build APKs for Android Emulators and devices: https://docs.expo.dev/build-reference/apk/

This article was synchronized and updated to xLog by Mix Space. The original link is https://fmcf.cc/posts/technology/Fiora-Setup-Guide