Starting from Scratch: Deploying the Mix Space Backend with 1Panel

Note
This is the first part of the "Mix Space + Yohaku Deployment Series", focusing on the backend (Core) installation. For the deployment of the frontend theme Yohaku, please refer to the second part.

Mix Space is a modern, decoupled personal blogging system. The backend Core provides a full suite of services including RESTful API, scheduled tasks, backups, serverless functions, and is the quietly beating heart of the entire system; the frontend theme is separate and can be freely paired.

This article will guide you through using the 1Panel panel to run the Mix Space backend on your own server—no fuss, just step by step.

Step 1 · Install 1Panel Panel

1Panel is a modern, open-source Linux server management panel with a clean interface and intuitive operation. With it, tasks like container management, file uploads, and reverse proxy setup become extremely convenient.

A Quick Pre-installation Check

Check Item	Requirement
Operating System	Mainstream Linux distributions (Debian / Ubuntu / CentOS, etc.)
Server Architecture	`x86_64`, `aarch64`, `armv7l`, etc. are all supported
Available Memory	Recommended 1 GB or more
Network Environment	Must be able to access the internet normally
Browser	Modern browsers like Chrome, Firefox, Edge, etc.

One Command to Install

SSH into your server and run:

BASH

bash -c "$(curl -sSL https://resource.fit2cloud.com/1panel/package/v2/quick_start.sh)"

Follow the command-line prompts and wait patiently for the installation to complete. Once successful, the console will display access information similar to this:

LOG

面板地址：http://你的服务器IP:端口/安全入口

Cloud server users, please note: remember to open the corresponding port in your security group; otherwise, the browser will not be able to access the panel.

Forgot the security entrance? SSH back into your server and run the following command; the value of the entrance field is the entrance path:

BASH

1pctl user-info

If Docker installation fails, run this command separately to fix it:

BASH

bash <(curl -sSL https://linuxmirrors.cn/docker.sh)

Step 2 · Installing Mix Space via 1Panel

2.1 Download the Application Package

Download the mxspace.zip file from the following repository for later use:

yohaku-docker-build1

Shell

2.2 Upload the Application Package

/opt/1panel/resource/apps/local

Click Upload and select the mxspace.zip file you just downloaded.

2.3 Extract and Pay Attention to the Path!

After uploading, click mxspace.zip and select Extract.

This step is crucial!

During extraction, you need to manually set the target path to:

/opt/1panel/resource/apps/local/mxspace

If the path is entered incorrectly, files will be scattered into the wrong directory, and the app store will not recognize this local application.

2.4 Sync Local Applications

Go to the 1Panel App Store, click the Sync Local Applications button in the top right corner, wait a moment, then type mxspace in the search box—you will see the app you just added.

Click Install to enter the configuration page.

2.5 Fill in Installation Configuration

On the installation page, there are three read-only notes and five configuration items. Fill them in from top to bottom:

Note
At the top of the page are three gray "📌" tips explaining the JWT secret requirements, domain format, and encryption function considerations. They are for reference only—no modification needed, just skip them.

🔑 JWT Secret

This is the core security credential for the backend service. It must be at least 16 characters and no more than 32 characters long. We recommend using a randomly generated strong password. You can generate one in the terminal with:

BASH

openssl rand -base64 24

Fill in the generated result here and keep it safely — it's like the key to this blog system. If lost, resetting it will be a hassle.

🌐 Allowed Origins

Enter the frontend domains that are allowed to access the backend API, separated by commas. Example format:

localhost:*,你的主题前端域名

When deploying the Yohaku frontend, fill in the domain where Yohaku resides. If you're not sure yet, you can fill in localhost:* for now and modify it later on the installed app's configuration page.

🔒 Enable Encryption

Dropdown selection, default is Off (recommended).

Encryption is irreversible. If enabled and you accidentally lose the key, data cannot be recovered. Unless you have specific needs, it's recommended to keep it off.

🗝️ Encryption Key

Only needed if you selected 'On' above. The key must be 64 characters of lowercase letters and digits, and can be generated with:

BASH

openssl rand -hex 32

If encryption is off, leave this blank.

🔢 HTTP Port

Defaults to 2333, usually no need to change. If there is a port conflict, you can change it to another available port.

Note
It's not recommended to enable external access for the port directly; instead, use reverse proxy in the next step to provide public access, which is safer and more standard.

2.6 Start Installation 🎉

Confirm the configuration is correct, then click Start Installation.

1Panel will automatically pull the three images innei/mx-server, mongo:7, redis:alpine and orchestrate them. The first installation needs to pull images, so please wait a few minutes.

When the status shows Running, the Mix Space backend is quietly up and running 🌿

Step 3 · Configure Reverse Proxy and HTTPS

Exposing the port directly is neither secure nor elegant. We recommend binding the service to your domain via Nginx reverse proxy and adding HTTPS to complete the setup.

Here is a complete Nginx configuration. It does something quite interesting—it places the routes for the frontend (Yohaku, port 2323) and the backend (Mix Space Core, port 2333) in the same server block, serving both via a single domain. Visitors access your blog, while the frontend pages and backend API work quietly behind the scenes, presenting only a clean domain to the outside.

In 1Panel's Website → OpenResty → Configuration File, or directly edit the Nginx config on your server, and insert the following:

Before using, replace the following with your own values:

your-domain → replace with the actual domain, appearing 7 times
your subnet range → replace with the actual subnet range, appearing 1 time
your server IP → replace with the actual server IP, appearing 1 time (in the set_real_ip_from field)
SSL certificate paths → replace with your actual certificate paths (ssl_certificate and ssl_certificate_key)
baidu_verify_*.html → if you don't need Baidu site verification, you can delete the corresponding location block

NGINX

server {
    # Listen on IPv4/IPv6 HTTP and HTTPS ports
    listen 80;
    listen [::]:80;
    listen 443 ssl;
    listen [::]:443 ssl;

    server_name your-domain;
    index index.php index.html index.htm default.php default.htm default.html;
    root /www/sites/your-domain/index;

    # Log file paths
    access_log /www/sites/your-domain/log/access.log main;
    error_log /www/sites/your-domain/log/error.log;
    error_page 404 /404.html;

    # Get real client IP from CDN/Proxy
    real_ip_recursive on;
    set_real_ip_from your subnet range (e.g., 172.19.0.0/16);
    set_real_ip_from your server IP;
    set_real_ip_from 127.0.0.1;
    real_ip_header X-Forwarded-For;

    # Pass client info to backend
    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 X-Forwarded-Proto $scheme;

    # SSL certificate and security configuration
    ssl_certificate /www/sites/your-domain/ssl/fullchain.pem;
    ssl_certificate_key /www/sites/your-domain/ssl/privkey.pem;
    ssl_protocols TLSv1.3 TLSv1.2;
    ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA256:!aNULL:!eNULL:!EXPORT:!DSS:!DES:!RC4:!3DES:!MD5:!PSK:!KRB5:!SRP:!CAMELLIA:!SEED;
    ssl_prefer_server_ciphers off;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    # Enable HTTP/2 and HSTS
    http2 on;
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains";

    # Directly return Baidu verification file
    location = /baidu_verify_codeva-46XKS9HVjs.html {
        root /www/sites/your-domain/index;
        default_type text/plain;
        try_files $uri =404;
    }

    # Root path: redirect after removing error parameter; otherwise normal forwarding
    location = / {
        if ($args ~* "error=please_restart_the_process") {
            return 301 $scheme://$host;
        }
        proxy_pass http://127.0.0.1:2323;
    }

    # Hide sensitive files
    location ~ ^/(\.user.ini|\.htaccess|\.git|\.env|\.svn|\.project|LICENSE|README.md) {
        return 404;
    }

    # ACME challenge directory
    location ^~ /.well-known/acme-challenge {
        allow all;
        root /usr/share/nginx/html;
    }

    # Deny access to dynamic files under .well-known
    location ~ ^/\.well-known/.*\.(php|jsp|py|js|css|lua|ts|go|zip|tar\.gz|rar|7z|sql|bak)$ {
        return 403;
    }

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

    # API, rendering, proxy forwarding
    location /api/v3    { proxy_pass http://127.0.0.1:2333/api/v3; }
    location /render    { proxy_pass http://127.0.0.1:2333/render; }
    location /proxy     { proxy_pass http://127.0.0.1:2333/proxy; }
    location /qaqdmin   { proxy_pass http://127.0.0.1:2333/proxy/qaqdmin; }

    # Other paths forwarded to backend (with buffer optimization)
    location / {
        proxy_buffer_size          128k;
        proxy_buffers              4 256k;
        proxy_busy_buffers_size    256k;
        proxy_pass http://127.0.0.1:2323;
    }

    # HTTP auto redirect to HTTPS
    if ($scheme = http) {
        return 301 https://$host$request_uri;
    }
    error_page 497 https://$host$request_uri;
}

Routing Logic Overview:

Path Prefix	Proxy Target	Description
`/api/v3`	Backend `:2333`	Mix Space REST API
`/socket.io`	Backend `:2333`	WebSocket real-time push
`/render`	Backend `:2333`	Server-side rendering interface
`/proxy`	Backend `:2333`	Proxy and admin backend entry
`/qaqdmin`	Backend `:2333`	Admin backend quick entry
All other paths	Frontend `:2323`	Yohaku pages

This means you only need one domain—your frontend blog and backend admin are under the same entry, clean and elegant.

After configuration, your backend-related addresses are as follows (you'll need them when deploying Yohaku):

后端 API 地址：https://你的域名/api/v2
后端网关地址：https://你的域名
管理后台地址：https://你的域名/qaqdmin

Please note these addresses.

Step 4 · Initialize Admin Backend

After reverse proxy setup, access the admin backend in your browser:

https://你的域名/qaqdmin

On first access, you'll be guided through initialization, including creating an admin account, filling in basic site info, etc. Just follow the prompts.

Frequently Asked Questions

Q: After installation, the container keeps restarting and can't start normally?

Most likely, MongoDB or Redis health checks haven't passed yet—they need a little time to fully initialize, and the Core container will automatically retry. Wait about 1 minute, and it should recover on its own. If the issue persists, check the specific error messages in the 1Panel container logs.

Q: What if I forgot to save the JWT secret?

In the 1Panel App Store's installed list, click Edit or Configure for mxspace to view the current environment variable values.

Q: How can I change the allowed origins?

Modify the ALLOWED_ORIGINS environment variable in the installed app's configuration page, save, and restart the container for it to take effect.

Q: Where is the data stored?

All data is persistently stored in the /opt/1panel/apps/local/mxspace/mxspace/data/ directory, including MongoDB data, Redis data, and mx-space runtime files. Regularly back up this directory, or include it in 1Panel snapshots.

References

The backend has landed firmly 🌱
Next, head to the second part to dress it up with the beautiful Yohaku theme.