#Rin (Yangjiao Express Secondary Development Edition) Deployment Guide

This document guides you through deploying the Yangjiao Express secondary development edition of Rin to Cloudflare from scratch.

#Prerequisites

• A GitHub account
• A Cloudflare account (free tier is sufficient)
• Approximately 10-15 minutes of your time

#Deployment Steps

#Step 1: Fork the Repository

This repository is the Yangjiao Express secondary development edition of Rin. It adds features that the official upstream does not have, including self-service friend links over email, TOTP two-factor authentication, and API keys. Fork this repository directly:

1. Visit Yangjiao Express Secondary Development Edition (this repository, recommended): https://github.com/wool-hmq/Rin
2. Click the "Fork" button in the top right corner
3. Select your personal account, keep the default settings, and click "Create fork"

Official upstream: openRin/Rin. It does not include the features added in this edition. Use it only when you explicitly want to follow upstream. The rest of this guide assumes the secondary development edition.

#Obtaining Account ID and API Token

Refer to https://developers.cloudflare.com/workers/wrangler/ci-cd/ to configure the Cloudflare login environment variables required for GitHub Actions.

Account ID: Click on any domain you have bound. After entering, you can find the Account ID on the right side (you need to scroll down a bit).

Creating an API Token: Click your Profile icon in the top right > My Profile > API Tokens > Create Token, and select the Edit Cloudflare Workers template:

Save the token after creation.

#Step 2: Configure GitHub Secrets

1. On your forked repository page, click the "Settings" tab
2. In the left menu, expand "Secrets and variables" and select "Actions"
3. Click the "New repository secret" button to add the following secrets:

#Required Secrets

Tip: JWT_SECRET can be any random string of any length, for example: MySecretKey123!@#

#Login Configuration Secrets

Rin currently supports username/password login and GitHub OAuth login. You can choose one or configure both.

Username/Password Login (Recommended)

GitHub OAuth Login (Optional)

If you want to use your GitHub account to log in, please refer to the Advanced Configuration section to add OAuth configuration.

Tip: Username/password login and GitHub OAuth login can be enabled simultaneously. Users can freely choose their preferred login method on the login page.

#Step 3: Trigger Deployment

1. Go to the "Actions" tab in your repository
2. Select the "Build" workflow on the left
3. Click the "Run workflow" button
4. Keep the default branch (main) and click "Run workflow"

The deployment process takes approximately 3-5 minutes. After Build succeeds it triggers the Deploy workflow through workflow_run. A manual Deploy run requires a build artifact URL.

Tip: The deployment script configures frontend environment variables automatically. Site name, description, Worker name, and similar values can be customized with GitHub Variables (see "Site Variables" below).

#Step 4: Access Your Blog

When deployment finishes, the Deploy workflow log prints the App URL. Both the frontend page and the backend API are served from that address. The default Worker name is rin-server and can be overridden with the WORKER_NAME variable.

#Step 5: First Login

1. Visit the frontend page
2. Click the login icon in the top right corner
3. Log in using the ADMIN_USERNAME and ADMIN_PASSWORD you set in Secrets
4. After logging in, click your avatar to enter the Profile page, where you can modify your nickname and upload an avatar

#Site Variables (Optional)

The following GitHub Variables override deployment defaults:

Email login, email verification codes, and self-service friend links over email also require EMAIL_SEND_URLS / EMAIL_SEND_KEYS; see Environment Variables.

#Publishing Your First Post

1. After logging in, click the "Write" button in the top right corner
2. Fill in the article title and content
3. Click the "Publish" button

🎉 Congratulations! Your Rin blog has been successfully deployed and your first post has been published!

#Advanced Configuration

#Custom Domain

1. Log in to the Cloudflare Dashboard
2. Go to Pages > Your Project > Custom Domains
3. Follow the prompts to add your domain

#Image Storage Configuration

Rin supports two storage methods: Cloudflare R2 (recommended) or S3-compatible storage.

#Using Cloudflare R2 (Recommended)

If no S3 environment variables are configured, the deployment script will automatically attempt to use Cloudflare R2. You only need to set the following in GitHub Variables:

The deployment script will automatically construct the R2 endpoint and access host. If you want to use a custom domain for images, you can additionally set:

#Using S3-Compatible Storage

If you need to use other S3-compatible storage (such as AWS S3, MinIO, etc.), you need to fully configure the following Secrets:

And the following Variables (optional):

#GitHub OAuth Configuration

If you want to log in with your GitHub account:

1. Visit GitHub Settings > Developer settings > OAuth Apps
2. Click "New OAuth App"
3. Fill in the application information:
   • Application name: Rin Blog
   • Homepage URL: Your frontend page address
   • Authorization callback URL: https://your-worker-name.your-account-id.workers.dev/api/user/github/callback
4. After creation, obtain the Client ID and Client Secret
5. Add to GitHub Secrets:
   • RIN_GITHUB_CLIENT_ID
   • RIN_GITHUB_CLIENT_SECRET

#Webhook Notifications

If you want Rin to send comment and friend-link notifications to a bot, chat service, or automation platform, see the Webhook Guide.

#Troubleshooting

#Deployment Failed

1. Check if GitHub Secrets are configured correctly
2. View the Actions logs for detailed error messages
3. Ensure your Cloudflare account has permissions for Workers, Pages, and D1

#Cannot Log In

1. Confirm that ADMIN_USERNAME and ADMIN_PASSWORD are set correctly
2. Check Worker logs for authentication errors
3. Clear browser cache and try again

#Database Migration Failed

The deployment script will automatically run database migrations. If it fails:

1. Manually go to Cloudflare Dashboard > D1
2. Find your database and click "Console"
3. Manually execute the migration SQL (refer to the files in server/sql/, in numeric order)

#GitHub Actions Workflows

The repository includes several GitHub Actions workflows that automate testing, building, and deployment:

#CI Workflow (ci.yml)

Runs on pushes to main / trunk and on pull requests:

• TypeScript type checking
• Formatting verification

#Test Workflow (test.yml)

Runs on pushes to main / trunk and on pull requests:

• Server tests: unit and integration tests using Bun
• Client tests: component tests using Vitest
• Type checking: tsc --noEmit for both client and server
• Build verification: production client build

#Build Workflow (build.yml)

Runs on pushes to main / master / trunk, on pull requests, or manually:

• Type checking
• Client build
• Server build through Wrangler dry-run
• Uploads build artifacts and triggers Deploy on success

#Deploy Workflow (deploy.yml)

Triggered automatically after a successful Build, or manually with a build artifact URL:

• Deploys the frontend to Cloudflare Pages
• Deploys the backend to Cloudflare Workers
• Runs D1 database migrations
• Prints the deployed App URL in the Actions log

#Docs Workflow (docs.yml)

Runs on pushes to main that touch docs/**:

• Builds the Rspress documentation site
• Publishes it to GitHub Pages

#Release Workflow (release.yml)

Runs when a vX.Y.Z tag is pushed:

• Validates version consistency across workspaces
• Runs type checking and builds
• Packages and publishes build artifacts

#PR Preview

Pull requests automatically get a preview deployment. clean.yml removes the preview Worker when the PR closes.

#Updating Your Blog

When a new version is released:

1. Click "Sync fork" on your forked repository page
2. Click "Update branch"
3. Deployment will be triggered automatically

#Update the Yangjiao Express Secondary Development Edition (Recommended)

# Add the secondary development repository as upstream
git remote add upstream https://github.com/wool-hmq/Rin.git
git fetch upstream
git checkout main
git merge upstream/main
git push origin main

#Sync the Official Upstream (Optional)

Use this only when you want to merge changes from the official upstream. The official upstream does not include this edition's features:

git remote add upstream https://github.com/openRin/Rin.git
git fetch upstream
git checkout main
git merge upstream/main
git push origin main

#Need Help?

• 📖 Yangjiao Express Secondary Development Edition docs
• 🐛 Yangjiao Express Secondary Development Edition issues
• 💬 Yangjiao Express Secondary Development Edition discussions
• 📖 Official upstream docs
• 🐛 Official upstream issues
• 💬 Official upstream discussions