Note

This is the second post in the "Mix Space + Yohaku Deployment Series," focusing on installing the frontend theme Yohaku. If you haven't deployed the backend yet, please read the first post—《From Zero: Deploying Mix Space Backend with 1Panel》 first.

Yohaku, taken from the Japanese word for "margin" or "blank space," refers to the intentional emptiness in a composition—often carrying more weight than the filled parts.

This is the latest generation frontend theme in the Mix Space ecosystem. Its story began with the open-source Shiro, evolved through the closed-source sponsored version Shiroi, and has now reached the current Yohaku—three generations of inheritance, with design language and implementation quietly iterating at each step. The entire site uses writing as a metaphor, with pages unfolding like a letter, using restrained colors and breathing animations to make reading itself the protagonist.

A simple overview of the relationship between the three generations of themes:

• Shiro → The original open-source frontend theme for Mix Space, code publicly available on GitHub
• Shiroi → A closed-source donation-based version of Shiro, evolving from Shiro, accessible after sponsorship
• Yohaku (余白) → A brand new design further evolved from Shiro / Shiroi, also maintained as a closed-source sponsored version, and is the latest generation

This article focuses on deploying Yohaku. Since it is a closed-source theme, you need to build the Docker image yourself. The following will guide you step-by-step. (This tutorial is also compatible with Shiroi)

Step 1 · Building the Docker Image

Since the author does not provide pre-built Docker images for the Shiroi / Yohaku theme, we need to build it ourselves. However, do NOT build directly on a low-spec server—the server's memory will be overwhelmed 💥

Our solution is to use GitHub Actions to complete the build in the cloud, then push the image to a private GitHub Packages (ghcr.io) repository. The server only needs to pull the ready-made image, which is very lightweight.

1.1 Fork the Build Repository

Visit the following repository and click Fork in the top right corner:

1.2 Apply for a GitHub Classic Access Token (Classic Token)

Actions need permission to read the Shiroi private repository and push the built image to GitHub Packages. We need to prepare a classic token (Classic Token) in advance.

Access path:

Fill in a note (e.g., shiroi-build), you can set the expiration to permanent, then check the following permissions:

Click Generate token, and immediately copy and save the generated Token—it will only be shown this once!

1.3 Configure Repository Actions Variables

Go to your forked repository, and click in order:

Add the following two variables:

1.4 Enable and Trigger the Build

Go to the repository's Actions tab, and click to enable if prompted. Then find the build Workflow, and click Run workflow on the right to trigger it manually once.

The build process usually takes 5 ~ 10 minutes, you can go make a cup of tea and wait ☕

After the build is complete, you can see your image in the Packages section of the repository sidebar. The address format is:

1.5 Configure the ghcr.io Private Repository in 1Panel

Since the image is stored in the private GitHub Container Registry, 1Panel needs to log in for authentication before it can pull.

Log into the 1Panel dashboard, go to Containers → Repositories → Create Repository, and fill in:

After saving, 1Panel will automatically verify the connection. This will ensure smooth pulling of private images in the future 🔐

Step 2 · Installing Yohaku via 1Panel

2.1 Upload the Application Package

Log into the 1Panel dashboard, go to the left menu Host → Files, and navigate to the path:

Click Upload, and select the yohaku.zip file you downloaded from your forked repository.

2.2 Extract, Pay Attention to the Path!

After the upload is complete, click on yohaku.zip and select Extract.

2.3 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 yohaku in the search box. You should see the application you just added.

Click Install to enter the configuration page.

2.4 Fill in the Installation Configuration Items

The installation page has four required fields (plus one read-only note). Fill them in from top to bottom:

🐳 Image Address (Image Address)

Fill in the container image here. Choose based on the version you are deploying:

Open-source version Shiro (use the official pre-built image directly):

Closed-source version Shiroi / Yohaku (fill in the private image you built in Step 1):

📡 Public API Address (PUBLICAPIURL)

Fill in your Mix Space backend API address:

Note: Keep the /api/v2 path at the end.

🌐 Public Gateway Address (PUBLICGATEWAYURL)

Fill in your Mix Space backend gateway address (i.e., the backend root domain):

Do not add any path suffix.

🔗 API URL and Client API Address

The values for API_URL and NEXT_PUBLIC_CLIENT_API_URL should be the same as the Public API Address. Fill in the same content:

2.5 Start Installation 🎉

Confirm the configuration is correct, then click Start Installation.

1Panel will automatically pull the image and start the container. This process may take a few minutes depending on network conditions. When the status shows Running, Yohaku is officially live!

Step 3 · Configuring Reverse Proxy and HTTPS

Refer to the previous blog post. If already configured, you can skip this.

Appendix: Extended Markdown Syntax Supported by Yohaku

Yohaku inherits from the Shiro system and supports a rich set of extended Markdown syntax, allowing your blog posts to be more than just plain text. Here are the special syntaxes you can use when writing—

Mathematical Formulas (KaTeX)

Inline formula:

Block-level formula:

Notice / Banner

GFM Alert Syntax

Spoiler Mask

Note: This is different from the strikethrough ~~text~~ effect. Spoiler hides content with a mask, revealing it only on mouse hover.

Rich Link

For links that are on their own line, Yohaku will automatically render them as cards with cover images and summaries:

Supported platforms include GitHub repositories, Commits, Issues, Gists, as well as YouTube, Twitter, etc.

Inline Link Icons

Inline links will automatically attach the corresponding website's Favicon:

Mention

GH@username will automatically render as a GitHub user card with an avatar.

Collapse Block

Frequently Asked Questions

Q: What should I do if the image pull speed is extremely slow or fails?

Pulling from ghcr.io on servers within China may be slow. You can add a step in the GitHub Actions build Workflow to synchronize and push to Alibaba Cloud ACR, then pull from Alibaba Cloud. For specific configuration, you can refer to Mint's Hut's tutorial.

Q: How to troubleshoot if the Actions build fails?

Go to the repository's Actions page, click on the failed Workflow to view detailed logs. Common reasons:

• GH_PAT permissions are insufficient, check if repo and write:packages are selected
• DOCKER_NAMESPACE is not all lowercase
• The repository is set to public, causing permission conflicts

Q: After extraction, the App Store cannot find yohaku?

Most likely the extraction path is incorrect. Please confirm the extraction target is /opt/1panel/resource/apps/local/yohaku (not /opt/1panel/resource/apps/local). After confirming, click "Sync Local Applications" again.

Q: The page is accessible, but it prompts backend connection failure?

Check the following points:

• Are the four API address configuration items filled in correctly, especially the /api/v2 path must not be omitted
• Does the Mix Space backend's ALLOWED_ORIGINS already include the Yohaku frontend domain
• Is the backend reverse proxy and HTTPS certificate working properly

References

The following materials were referenced during the writing of this article. Thanks to all the bloggers for their generous sharing 💝

• 1Panel Online Installation Documentation
• Building Shiroi Docker Image with GitHub Action · Miku's Aurora Star
• Mix Space + Shiro Full Containerized Deployment Guide · Mint's Hut
• Self-Creating 1Panel Applications · FIT2CLOUD Community Forum
• Self-Creating 1Panel Application Tool
• Shiro Extended Markdown Syntax Documentation
• Yohaku Theme Documentation
• Adding NEXTPUBLICCLIENTAPIURL
• Adding API_URL

Margins are an attitude. May your blog also become that letter worth unfolding carefully 🌿