jiuyue

Shiro, a minimalist personal website, as pure as paper and as fresh as snow.

innei boss and
Shiro: Shiro - A brand new style, setting sail again

Shiro/Shiroi is a front-end theme for Mix-Space, where Shiroi is the closed-source version, available through sponsorship of Innei Innei.
There are some differences in functionality between the open-source and closed-source versions, which can be seen in the official documentation.

Shiro and Related Projects#

Vercel Deployment#

For Shiro Vercel deployment, please refer to the official documentation

https://mx-space.js.org/themes/shiro

Cloud Server / Local Deployment#

System / Environment Requirements#

• Linux, kernel version >4.19 (recommended Debian 11 / 12) The tutorial takes Debian 11 / 12 as an example
• Server memory needs 2~4 GiB, only 512 MiB or even less is required to run after the build (if memory is small or available memory is insufficient, you can build locally or configure 2~4 GiB of Swap): The blogger's server is 2H-2G, so 4G Swap is configured.
• Use NVM to install Node.js v20.12.2, as well as PNPM / PM2 / sharp
• Use Screen to keep the background alive (optional)
• Use 1Panel + OpenResty (optional)

Necessary Preparations#

• Domain name: This article adopts the dual subdomain model, that is, front-end www.vlo.cc, back-end api.vlo.cc

• SSL certificate required for front-end and back-end domain names: Full site HTTPS is needed (for front-end access API issues, you can try adding localhost,127.0.0.1 to the back-end configuration file ALLOWED_ORIGINS)

1. NodeJS and Related Environment#

Refresh the system package cache and install commonly used/necessary software packages

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

1. Install NVM

    curl https://raw.githubusercontent.com/creationix/nvm/master/install.sh | bash

2. Run the command source ~/.profile to reload the environment variables into the current session.

 source ~/.profile

3. List the available versions of Node.JS.

nvm ls-remote

4. After determining the version, run the command nvm install *version* to download and install it. For example, to install Node.JS 20.12.2,
   Version V20.12.2 is strongly recommended

# Install
nvm install 20.12.2
# Check version
node -v

5. Install pnpm and pm2

npm install -g pnpm pm2

6. Install sharp

  npm i -g sharp
  pnpm add sharp
  # Configure sharp environment variable
  # export NEXT_SHARP_PATH=/root/node_modules/sharp

2. Configuration and Build of Shiro#

1. Core Back-end Cloud Function Configuration#

For specifics, refer to the official documentation:
** Back-end Theme Configuration **

Enter the Mix Space backend, go to the "Configuration and Cloud Functions" page, click the add button in the upper right corner, and fill in the following settings on the edit page:

• Name: shiro
• Reference: theme
• Data Type: JSON
• Data: Copy the following example on the right and change it to your own information

{
 "footer": {
   "otherInfo": {
     "date": "2022-{{now}}",
     "icp": {
       "text": "豫 ICP 备 2022029096号-2",
       "link": "https://beian.miit.gov.cn"
     }
   },
   "linkSections": [
     {
       "name": "😊About",
       "links": [
         {
           "name": "About Me",
           "href": "/about"
         },
         {
           "name": "About This Project",
           "href": "https://github.com/innei/Shiro",
           "external": true
         }
       ]
     },
     {
       "name": "🧐More",
       "links": [
         {
           "name": "Timeline",
           "href": "/timeline"
         },
         {
           "name": "Friend Links",
           "href": "/friends"
         },
         {
           "name": "Monitoring",
           "href": "https://halo.vlo.cc",
           "external": true
         }
       ]
     },
     {
       "name": "🤗Contact",
       "links": [
         {
           "name": "Leave a Message",
           "href": "/message"
         },
         {
           "name": "Send Email",
           "href": "mailto:i@vlo.cc",
           "external": true
         },
         {
           "name": "GitHub",
           "href": "https://github.com/jiuyue52",
           "external": true
         }
       ]
     }
   ]
 },
 "config": {
   "color": {
     "light": [
       "#33A6B8",
       "#FF6666",
       "#26A69A",
       "#fb7287",
       "#69a6cc",
       "#F11A7B",
       "#78C1F3",
       "#FF6666",
       "#7ACDF6"
     ],
     "dark": [
       "#F596AA",
       "#A0A7D4",
       "#ff7b7b",
       "#99D8CF",
       "#838BC6",
       "#FFE5AD",
       "#9BE8D8",
       "#A1CCD1",
       "#EAAEBA"
     ]
   },
   "custom": {
     "css": [],
     "styles": [],
     "js": [],
     "scripts": []
   },
   "site": {
     "favicon": "https://halo.vlo.cc/upload/pic/J99Y.svg",
     "faviconDark": "https://halo.vlo.cc/upload/pic/J99Y.svg"
   },
   "hero": {
     "title": {
       "template": [
         {
           "type": "h1",
           "text": "Hi, I'm ",
           "class": "font-light text-4xl"
         },
         {
           "type": "h1",
           "text": "JiuYue",
           "class": "font-medium mx-2 text-4xl"
         },
         {
           "type": "h1",
           "text": "👋。",
           "class": "font-light text-4xl"
         },
         {
           "type": "br"
         },
         {
           "type": "h1",
           "text": "Language is the direct reality of thought",
           "class": "font-light text-4xl"
         },
         {
           "type": "code",
           "text": "<Developer />",
           "class": "font-medium mx-2 text-3xl rounded p-1 bg-gray-200 dark:bg-gray-800/0 hover:dark:bg-gray-800/100 bg-opacity-0 hover:bg-opacity-100 transition-background duration-200"
         },
         {
           "type": "span",
           "class": "inline-block w-[1px] h-8 -bottom-2 relative bg-gray-800/80 dark:bg-gray-200/80 opacity-0 group-hover:opacity-100 transition-opacity duration-200 group-hover:animation-blink"
         }
       ]
     },
     "description": "When the heart is serene, there is joy in every direction."
   },
   "module": {
     "activity": {
       "enable": true,
       "endpoint": "/fn/ps/update"
     },
     "donate": {
       "enable": true,
       "link": "https://afdian.net/@huasui",
       "qrcode": [
         "https://halo.vlo.cc/upload/pic/wxdashang.png",
         "https://halo.vlo.cc/upload/pic/wxdashang.png"
       ]
     },
     "bilibili": {
       "liveId": 23359061
     }
   }
 }
}

2. Pull Shiro/Shiroi#

   cd /opt/mx-space
    # Personal habit to deploy Mx-Space and front-end Shiro/Kami under /opt/mx-space
    # So here ./mx-space is the mx back-end/front-end project folder
   git clone https://github.com/Innei/Shiro.git
    # The shiroi repository can be obtained through sponsorship

3. Configure .env#

Copy .env.example to .env and edit the .env file

  cd /opt/mx-space/Shiro
  mv .env.template .env
  vim .env

Example .env

# Back-end API address
NEXT_PUBLIC_API_URL=https://api.example.com/api/v2
# Back-end gateway address
NEXT_PUBLIC_GATEWAY_URL=https://api.example.com
# TMDB information retrieval
TMDB_API_KEY=
# GitHub token, used to retrieve front-end version hash
GH_TOKEN=

4. Start Building the Shiro/Shiroi Project#

  cd /opt/mx-space/Shiro
  pnpm i && pnpm build

::: warning
If the server's region cannot access the official NPM source, it may cause dependency installation failures and result in the following error

Solution: Manually modify the project .npmrc configuration file before building

cd /opt/mx-space/Shiro
vim .npmrc
  # 1 ↑ Change the registry to the taobao source (https://registry.npmmirror.com) or other domestic mirror sources
  # nrm use taobao
  # 2 ↑ If nrm (npm's mirror source management tool) is installed, you can also use nrm
pnpm i && pnpm build
  # Finally reinstall dependencies and build

:::
Building takes a long time, please be patient...

::: gallery


:::

3. Shiro Start!#

1. Start directly in the front end, run in the Shiro root directory
   pnpm prod:pm2, you can use nohup or other methods to run it in the background

2. Use Screen to keep it alive in the background (recommended)

apt install screen -y
  # Install Screen on Debian/Ubuntu
screen -R shiro
  # Create a new shiro session
cd /opt/mx-space/Shiro
npx next start -p 2323
# pnpm prod:pm2
  # Start shiroi

After starting, press Ctrl +A+D to exit and suspend the shiro session, completing Shiro's background operation.

Note: Both startup methods need to restart Shiro after restarting the servers.

Screen usage tutorial: https://www.mintimate.cn/2021/09/02/howToUseScreen/
A very good tutorial.

4. Reverse Proxy and Update#

1. Reverse Proxy#

Taking 1Panel + OpenResty as an example

1. Create a static website
2. Configure SSL certificate to enable HTTPS
3. Add a new line for CV reverse proxy configuration below add_header Strict-Transport-Security "max-age=31536000"; or above the last }

## Reverse proxy starts 
    location ~* \.(gif|png|jpg|css|js|woff|woff2|svg|webp)$ {
      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-Proto $scheme;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header REMOTE-HOST $remote_addr;
      expires 30d;
    }
    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-Proto $scheme;
      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 / {
      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-Proto $scheme;
      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 no-cache;
      proxy_intercept_errors on;
    }
    ## Reverse proxy ends

## Reverse proxy starts, directly copy the official documentation
    ## WebSocket address
    location /socket.io {
        proxy_set_header Upgrade $http_upgrade; 
        proxy_set_header Connection "Upgrade"; 
        proxy_buffering off; 
        proxy_set_header Host $host; 
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; 
        proxy_set_header X-Forwarded-Proto $scheme; 
        proxy_pass http://127.0.0.1:2333/socket.io; 
    }
    ## API address
    location /api/v2 {
        proxy_pass http://127.0.0.1:2333/api/v2; 
    }
    ## Simple read render address
    location /render {
        proxy_pass http://127.0.0.1:2333/render; 
    }
    ## Front-end address
    location / {
        proxy_pass http://127.0.0.1:2323; 
    }
    ## Back-end address
    location /proxy {
        proxy_pass http://127.0.0.1:2333/proxy;
    }
    location /qaqdmin {
        proxy_pass http://127.0.0.1:2333/proxy/qaqdmin;
    }
    ## RSS address
    location ~* \/(feed|sitemap|atom.xml) {
        proxy_pass http://127.0.0.1:2333/$1; 
    }
    ## Reverse proxy ends

2. Shiro Update#

# Enter the working directory
cd /opt/mx-space/Shiro
# Update
git pull
# git push
screen -R shiroi -X quit
# nrm use taobao (choose whether to change the source based on server location/network conditions)
# Install dependencies and build
pnpm i && pnpm build
# Use screen to achieve background startup
screen -R shiroi
npx next start -p 2323

The above update method has not been tried, but I have tried it, and it works great! It is referenced from Arthalsstolen

If the domestic server cannot pull git, I can only use a clumsy method to update: pull git locally and upload it to the server, then repeat the process from 2. Configuration and Build of Shiro 2 to 4 again🤣（🥹

3. Markdown Extended Syntax#

Please read https://shiro.innei.in/#/markdown

5. Pitfalls#

1. Font Fetching Failure#

Shiro will fetch font files during the build,
If the server cannot ping fonts.googleapis.com / fonts.gstatic.com,
It may result in the following error, ultimately causing the build to fail

It seems that the IP resolved by the server is not good.....

Solution: Change the hosts file to specify a server that can ping fonts.googleapis.com / fonts.gstatic.com

You can use itdog to check the IP of the font domain name, then try pinging from the server, whichever can ping is the one to change.

2. OAuth2 Related Issues#

1. Callback Error redirect_uri

Second Method: Copy the new dual domain reverse proxy configuration from the Core/Shiro deployment articles.

FAQ:

What changes are there in the new configuration file?

I added the following configuration to each location in the original front-end and back-end reverse proxy configuration example file (it seems that adding it to the back-end is enough, but I added it to both for safety).

What if redirect_uri still doesn't work after doing this?

It is likely a caching issue; clear the cache OR test whether it works in private browsing mode.

location / {
    ...
    proxy_set_header X-Forwarded-Proto $scheme;
    ...
}

2. Back-end Not Recognizing Owner

If your back-end core version is between 7.0.3-7.0.6, or if you start configuring OAuth in a version after 7.0.6, and it is consistently unsuccessful (the reason may be a bug in a certain version, and upgrading Core may not solve it; reverting to an earlier version may resolve it).

Including but not limited to: back-end not recognizing owner, front-end and back-end owners unable to log in, redirect_url errors, etc.

You can try reverting Core to version 7.0.2-alpha.0: configure oauth and verify it as the owner account, and test logging in using OAuth for both front-end and back-end (if there are still redirect_url issues, it may be due to caching; you can try testing in a new environment). If the tests are successful, directly upgrade to the latest version.

Reference Articles#

Thanks to the official and community contributors!

Arthals: mx-space + Shiro: A blog as pure as paper

Official Documentation

Yukina

This article is synchronized and updated to xLog by Mix Space. The original link is https://www.vlo.cc/posts/jc/shiro