mx-space construction process record

Preface#

As you can see, my personal homepage has undergone a slight modification. Previously, it was a page completely handcrafted by the webmaster using MDUI (archive), but obviously, it was very rough and did not have the functionality to publish content. Recently, I saw some friends playing with mx-space, took a look, and felt it was quite good, so I spent some time deploying it on my personal homepage.

The main purpose of writing this article is to document the process, as it took me from evening until six in the morning to set this up due to the many pitfalls in the official documentation (this really needs to be criticized; following the documentation doesn't necessarily mean you can set up the site), so I decided to write down my setup process. One, to have something on my blog (this should be the first article), and two, to help others avoid some pitfalls.

Additionally, this article mainly serves as a supplement to the official documentation, so much of the content is consistent with the official documentation. Since the official documentation is constantly being updated, if you encounter discrepancies between the content described in this article and the documentation, please refer to the official documentation first.

Environment Preparation#

I am using Tencent Cloud's lightweight Singapore 2C4G, with the system being Debian 10, and I have installed the Baota panel (of course, you can also choose not to use Baota, but then you need to configure the reverse proxy yourself).

The requirements given in the official documentation are that the Linux kernel version should not be less than 4.19, and the memory should be greater than 1 GiB.

You can check the Linux kernel version using the command uname -r. If the version does not meet the requirements, please change the kernel/system yourself; I will not elaborate further here.

Since I am using Debian 10, the package manager is apt, so this tutorial may only be applicable to Debian/Ubuntu and its derivatives. Please resolve any issues you may encounter on other distributions yourself.

I recommend executing the entire installation process as the root user (ordinary users can switch to the root user using sudo -i), as I cannot guarantee success when installing under an ordinary user.

Dependency Installation#

Install Required Software Packages#

Connect to the terminal via ssh or other means and execute the following command:

apt update && apt install git curl vim wget git-lfs -y

Wait for the installation to complete.

Install Docker (Backend Dependency)#

You can quickly install Docker using the one-click script provided by Docker:

curl -fsSL https://get.docker.com | bash -s docker

# For servers in mainland China, please execute the following command to use the mirror source
curl -fsSL https://get.docker.com | bash -s docker --mirror AzureChinaCloud

After the installation is complete, please execute docker compose version to check if the output is normal.

Install Node.js and Dependency Modules (Frontend Dependency)#

Here, follow the mx-space official documentation to install nvm for managing Node.js.

If you are using the Baota panel like I am, please go to the Baota panel - Software Store - Runtime Environment, and install the PM2 Manager.

If you are not a Baota panel user, please execute the following command to install nvm:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash

# For servers in mainland China, please execute the following command to use the mirror source
bash -c "$(curl -fsSL https://gitee.com/RubyKids/nvm-cn/raw/master/install.sh)"

After installation, please restart the terminal, then execute npm -v to check if there is output.

Next, install Node.js:

nvm install --lts
# Baota panel users can skip this step, as Node.js will be automatically installed when installing PM2 Manager

Install the required modules:

# For servers in mainland China, please execute the following command to switch the mirror source
npm config set registry http://mirrors.cloud.tencent.com/npm/

npm install -g pnpm pm2

Deploy Backend#

Pull Docker Configuration Files#

# Create a new folder
cd && mkdir -p mx-space/core && cd $_

# Pull docker-compose.yml file
wget https://fastly.jsdelivr.net/gh/mx-space/core@master/docker-compose.yml

# Pull Core configuration file
wget https://fastly.jsdelivr.net/gh/mx-space/core@master/.env.example -O .env

Edit Backend `.env` Environment Configuration File#

Edit using vim: vim .env

Press i to enter edit mode, then modify according to the following:

# THIS ENV FILE EXAMPLE ONLY FOR DOCKER COMPOSE
# SEE https://docs.docker.com/compose/environment-variables/#the-env-file

# Fill in a string with a length of no less than 16 characters and no more than 32 characters
JWT_SECRET=7294c34e0b28ad28

# Replace this with your frontend domain name. If multiple domain names are allowed, separate them with commas
ALLOWED_ORIGINS=example.com,www.example.com

# must be 64bit
# ===
# This has not been defined by the new version of the documentation, and it is not recommended to modify it. If necessary, you can try:
# openssl rand -hex 32
# to generate a new Encrypt_Key.
# ===
ENCRYPT_KEY=593f62860255feb0a914534a43814b9809cc7534da7f5485cd2e3d3c8609acab

After modifying, press ESC to exit edit mode, then type :wq and press Enter to leave vim.

Start the Backend#

docker compose up -d

Use curl to Test Backend Status#

Execute the command: curl http://127.0.0.1:2333/api/v2
If everything is normal, you will see output as follows:

root@mx-space:~/mx-space/core# curl http://127.0.0.1:2333/api/v2
{"name":"@mx-space/core","author":"Innei <https://innei.ren>","version":"3.41.2","homepage":"https://github.com/mx-space/core#readme","issues":"https://github.com/mx-space/core/issues"}

At this point, the backend deployment is complete.

Deploy Frontend#

Pull Kami Source Code#

Kami is the default frontend for mx-space, and you can also use other styled frontends like mx-web-yun.

# Pull source files
cd && cd mx-space
git clone https://github.com/mx-space/kami.git --depth 1
git clone https://ghproxy.com/github.com/mx-space/kami.git --depth 1 # For servers in mainland China, please execute this command to use the mirror source

# Switch to the latest tag
cd kami && git fetch --tags && git checkout $(git rev-list --tags --max-count=1)

# Pull image files
git lfs fetch --all
git lfs pull

Note: If you cannot pull normally, you can manually download the files from GitHub and place them in the corresponding directory.

Edit Frontend `.env` Environment Configuration File#

Copy .env.example to .env:

cp .env.example .env

Edit using vim: vim .env

It should look like this:

# API Address
NEXT_PUBLIC_API_URL=https://server.test.cn/api/v2
# GATEWAY Address
NEXT_PUBLIC_GATEWAY_URL=https://server.test.cn
# Configuration item name used by the frontend
NEXT_PUBLIC_SNIPPET_NAME=kami
# If using CDN, modify the product prefix; generally leave it blank
ASSETPREFIX=

In vim, we can use the find and replace feature for quick modifications. Just enter :g/server.test.cn/s//your-domain/g and press Enter to replace the original domain.

After completing, press ESC to exit edit mode, then type :wq and press Enter to leave vim.

Build Kami#

# Install required modules
pnpm i
# Build
pnpm build

The compilation process will take some time, please keep the terminal connected normally.

Start Kami#

pnpm prod:pm2

Use curl to Test Frontend Status#

Execute the command: curl http://127.0.0.1:2333/api/v2
If there is a return result, it is considered normal.

Configure Reverse Proxy#

I am using the Baota panel and have installed Nginx. If you are using other servers like Caddy or not using the Baota panel, please explore on your own.

Go to the Baota panel - Website, set the website address and resolve it yourself.

After creating the site, go to Settings - Reverse Proxy - Add Reverse Proxy.

The proxy name can be anything.

Target URL: http://127.0.0.1:2333 Send Domain: $host

After saving, click Configuration File, delete all content, and copy the configuration file content below:

#PROXY-START/
# generated 2023-01-25
# by bdovo.cc

location ~* \/(feed|sitemap|atom.xml)
{
    proxy_pass http://127.0.0.1:2333/$1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header REMOTE-HOST $remote_addr;
    
    add_header X-Cache $upstream_cache_status;
     
    add_header Cache-Control max-age=60;
} 

location /socket.io {
    proxy_http_version 1.1;
    proxy_buffering off;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_pass http://127.0.0.1:2333/socket.io;
}

location /api
{
    proxy_pass http://127.0.0.1:2333/api;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header REMOTE-HOST $remote_addr;

    add_header X-Cache $upstream_cache_status;

    #Set Nginx Cache

    set $static_fileJsNv8TWb 0;
    if ( $uri ~* "\.(gif|png|jpg|css|js|woff|woff2)$" )
    {
        set $static_fileJsNv8TWb 1;
        expires 12h;
    }
    if ( $static_fileJsNv8TWb = 0 )
    {
        add_header Cache-Control no-cache;
    }
}

location /proxy
{
    proxy_pass http://127.0.0.1:2333/proxy;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header REMOTE-HOST $remote_addr;

    add_header X-Cache $upstream_cache_status;

    #Set Nginx Cache

    set $static_fileJsNv8TWb 0;
    if ( $uri ~* "\.(gif|png|jpg|css|js|woff|woff2)$" )
    {
        set $static_fileJsNv8TWb 1;
        expires 12h;
    }
    if ( $static_fileJsNv8TWb = 0 )
    {
        add_header Cache-Control no-cache;
    }
}

location /admin # You can change this to your desired backend access path
{
    proxy_pass http://127.0.0.1:2333/proxy/qaqdmin;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header REMOTE-HOST $remote_addr;

    add_header X-Cache $upstream_cache_status;

    #Set Nginx Cache

    set $static_fileJsNv8TWb 0;
    if ( $uri ~* "\.(gif|png|jpg|css|js|woff|woff2)$" )
    {
        set $static_fileJsNv8TWb 1;
        expires 12h;
    }
    if ( $static_fileJsNv8TWb = 0 )
    {
        add_header Cache-Control no-cache;
    }
}

location /
{
    proxy_pass http://127.0.0.1:2323;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header REMOTE-HOST $remote_addr;

    add_header X-Cache $upstream_cache_status;

    #Set Nginx Cache

    set $static_fileSw1Jy3nG 0;
    if ( $uri ~* "\.(gif|png|jpg|css|js|woff|woff2)$" )
    {
        set $static_fileSw1Jy3nG 1;
        expires 12h;
    }
    if ( $static_fileSw1Jy3nG = 0 )
    {
        add_header Cache-Control no-cache;
    }
}
#PROXY-END/

Configure SSL Certificate#

This is similar to setting up an ordinary website, configure the SSL certificate in your preferred way.

If you are using the Baota panel, you can also directly use the built-in Let's Encrypt (please use DNS verification after configuring the reverse proxy).

I will not elaborate further here; those who need it can search for relevant tutorials themselves.

Backend Initialization#

Access the backend address for initialization.

If you directly used the Nginx reverse proxy configuration provided above, you should visit https://your-domain/admin.

Then fill in the relevant information.

Your API endpoint is:

API Address: https://your-domain/api/v2
Gateway Address: https://your-domain

Then follow the prompts to enter the initialization process. If you do not enter smoothly, try refreshing or going back one level.

Completion#

At this point, you should be able to access the frontend page through the domain name. The deployment phase ends here. If you need advanced settings, please refer to the official documentation.

So, start using your mx-space.

Enjoy it~

References#

mx-space Official Documentation: https://mx-space.js.org
Super Cute Frontend and Backend Separation Blog Mix-space Setup - Miao Er's Small Blog: https://www.miaoer.xyz/posts/blog/mx-install
Hello, Mix Space. - Shiinayuki's Blog: https://shiinayuki.me/posts/experiences/hello_mx-space

This article is synchronized and updated to xLog by Mix Space. The original link is https://bdovo.cc/posts/experiences/build_mx-space