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 site owner using MDUI (archive), but obviously, this thing was very rough and did not have the functionality to publish content. Recently, I saw a friend 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 that setting this up kept me busy from evening until six in the morning because there were too many pitfalls in the official documentation (this really needs to be criticized; following the documentation might not even get the site built), so I decided to write down my setup process. First, it allows my blog to have some content (this should be the first article), and second, it can help future readers 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 continuously 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 be no 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); I cannot guarantee success if installed under a normal 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, we will install nvm according to the mx-space official documentation to manage Node.js.

If you are using the Baota panel like I am, please go to the Baota panel - Software Store - Runtime Environment to 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 any output.

Next, install Node.js:

nvm install --lts
# Baota panel users can skip this step; 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 first
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 the docker-compose.yml file
wget https://fastly.jsdelivr.net/gh/mx-space/core@master/docker-compose.yml

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

Edit the 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

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

# must be 64bit
# ===
# This has not been defined in 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 making the modifications, 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 the 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 empty
ASSETPREFIX=

In vim, we can use the find and replace function for quick modifications by simply entering :g/server.test.cn/s//your domain/g and pressing 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 takes 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 Caddy or other servers or not using the Baota panel, please explore on your own.

Go to the Baota panel - Websites, 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 Sending Domain: $host

After saving, click on 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 SSL certificates for regular websites, 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 in need can search for relevant tutorials.

Backend Initialization#

Access the backend address for initialization.

If you directly use the Nginx reverse proxy configuration provided above, you should access 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 via the domain. 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 front-end and back-end separation blog Mix-space setup - Miao Er's small blog: https://www.miaoer.xyz/posts/blog/mx-install
Hello, Mix Space. - Shiina Yuki'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