Skip to content

Commit 387b80b

Browse files
OXeuOXeu
committed
init: docs
1 parent 699567f commit 387b80b

26 files changed

+1380
-0
lines changed

‎.gitignore

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Logs
2+
logs
3+
*.log
4+
npm-debug.log*
5+
yarn-debug.log*
6+
yarn-error.log*
7+
pnpm-debug.log*
8+
lerna-debug.log*
9+
10+
node_modules
11+
dist
12+
dist-ssr
13+
*.local
14+
bun.lockb
15+
16+
# Editor directories and files
17+
.vscode/*
18+
!.vscode/extensions.json
19+
.idea
20+
.DS_Store
21+
*.suo
22+
*.ntvs*
23+
*.njsproj
24+
*.sln
25+
*.sw?
26+
doc_build

‎docs/en/_meta.json

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
[
2+
{
3+
"text": "Guide",
4+
"link": "/en/guide/",
5+
"activeMatch": "/guide/"
6+
},
7+
{
8+
"text": "Env",
9+
"link": "/en/env/",
10+
"activeMatch": "/env/"
11+
}
12+
]

‎docs/en/env.md

+56
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Environment Variables List
2+
3+
## Frontend Environment Variables List
4+
5+
| Name | Required | Description | Default Value | Example Value |
6+
|--------------|----------|-----------------------------------------|---------------|----------------------------------------------------|
7+
| API_URL | Yes | Backend URL | None | http://localhost:3001 |
8+
| AVATAR | Yes | Avatar URL for the top left of the site | None | https://avatars.githubusercontent.com/u/36541432 |
9+
| NAME | Yes | Name & Title for the top left of the site | None | Xeu |
10+
| DESCRIPTION | No | Description for the top left of the site | None | Omnivore |
11+
| PAGE_SIZE | No | Default pagination limit | 5 | 5 |
12+
| RSS_ENABLE | No | Enable RSS (displays RSS link at the bottom of the site if enabled) | false | true |
13+
14+
**Deployment Environment Variables**
15+
16+
:::caution
17+
The following environment variables are required for deployment to Cloudflare Pages and cannot be modified.
18+
:::
19+
20+
| Name | Value | Description |
21+
|--------------------------|-----------------------------------------------------------|-------------------------------|
22+
| SKIP_DEPENDENCY_INSTALL | true | Skip the default npm install command |
23+
| UNSTABLE_PRE_BUILD | asdf install bun latest && asdf global bun latest && bun i | Install and use Bun for dependency installation |
24+
25+
## Backend Environment Variables List
26+
27+
**Plaintext Environment Variables**
28+
29+
:::note
30+
The following variables can remain unencrypted in Cloudflare Workers.
31+
:::
32+
33+
| Name | Required | Description | Default Value | Example Value |
34+
|-------------------|----------|-------------------------------------------------------|----------------|-------------------------------------------------------------------|
35+
| FRONTEND_URL | Temporarily required | Required for including comment article link in comment notification Webhook, can be left blank | None | https://xeu.life |
36+
| S3_FOLDER | Yes | File path for storing resources when uploading images | None | images/ |
37+
| S3_BUCKET | Yes | Name of the S3 bucket | None | images |
38+
| S3_REGION | Yes | Region of the S3 bucket, use 'auto' for Cloudflare R2 | None | auto |
39+
| S3_ENDPOINT | Yes | Endpoint address of the S3 bucket | None | https://1234567890abcdef1234567890abcd.r2.cloudflarestorage.com |
40+
| WEBHOOK_URL | No | Target address for sending Webhook notifications when a new comment is added | None | https://webhook.example.com/webhook |
41+
| S3_ACCESS_HOST | No | Access address of the S3 bucket | S3_ENDPOINT | https://image.xeu.life |
42+
| S3_CACHE_FOLDER | No | S3 cache folder (for SEO and high-frequency request caching) | cache/ | cache/ |
43+
44+
**Encrypted Environment Variables**
45+
46+
:::note
47+
All of the following variables are required (except Webhook) and must be encrypted after debugging in Cloudflare Workers. Unencrypted variables will be cleared during deployment if not listed in `wrangler.toml`.
48+
:::
49+
50+
| Name | Description | Example Value |
51+
|--------------------------|----------------------------------------------------------|-----------------------------------------------------------------|
52+
| RIN_GITHUB_CLIENT_ID | Client ID for GitHub OAuth | Ux66poMrKi1k11M1Q1b2 |
53+
| RIN_GITHUB_CLIENT_SECRET | Client secret for GitHub OAuth | 1234567890abcdef1234567890abcdef12345678 |
54+
| JWT_SECRET | Secret key required for JWT authentication, can be any regular format password | J0sT%Ch@nge#Me1 |
55+
| S3_ACCESS_KEY_ID | KEY ID required for accessing the S3 bucket, for Cloudflare R2 use an API token ID with R2 edit permissions | 1234567890abcdef1234567890abcd |
56+
| S3_SECRET_ACCESS_KEY | Secret required for accessing the S3 bucket, for Cloudflare R2 use an API token with R2 edit permissions | 1234567890abcdef1234567890abcd|

‎docs/en/guide/_meta.json

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
["index","changelog","deploy","seo","rss","contribution"]

‎docs/en/guide/changelog.md

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Changelog
2+
3+
### v0.2.0 Updated on 2024-06-07
4+
5+
- Added `S3_CACHE_FOLDER` environment variable
6+
- Updated the list of encrypted environment variables, keeping only the essential ones
7+
- Encrypted variables can now be configured directly via GitHub
8+
- Updated GitHub variable configuration, added encrypted variables that must be configured through GitHub (S3 storage for SEO index storage)
9+
- `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` are now prefixed with `RIN_` (`RIN_GITHUB_CLIENT_ID`, `RIN_GITHUB_CLIENT_SECRET`) to solve the issue where GitHub variables cannot start with `GITHUB_`. Variables configured through the Cloudflare panel (`GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET`) are not affected.
10+
11+
## Migration Guide
12+
13+
For normal version updates without special instructions, simply synchronize the forked repository.
14+
15+
### v0.2.0 Migration Guide
16+
17+
- Due to the introduction of SEO optimization, it is necessary to configure S3 storage environment variables in GitHub. Therefore, you need to additionally configure the following environment variables in GitHub (plain text, add to Variables):
18+
19+
```ini
20+
SEO_BASE_URL=<SEO base URL for SEO indexing, defaults to FRONTEND_URL>
21+
SEO_CONTAINS_KEY=<SEO indexing only includes links starting with SEO_BASE_URL or containing the SEO_CONTAINS_KEY keyword, defaults to empty>
22+
S3_FOLDER=<Folder for storing S3 image resources, defaults to 'images/'>
23+
S3_CACHE_FOLDER=<S3 cache folder (for SEO and high-frequency request caching), defaults to 'cache/'>
24+
S3_BUCKET=<Name of the S3 bucket>
25+
S3_REGION=<Region of the S3 bucket, use 'auto' if using Cloudflare R2>
26+
S3_ENDPOINT=<S3 bucket endpoint address>
27+
S3_ACCESS_HOST=<S3 bucket access address, without trailing '/'>
28+
```
29+
30+
Additionally, add the following encrypted environment variables (encrypted, add to Secrets):
31+
32+
```ini
33+
S3_ACCESS_KEY_ID=<Your S3AccessKeyID>
34+
S3_SECRET_ACCESS_KEY=<Your S3SecretAccessKey>
35+
```
36+
37+
These environment variables were previously configured through the Cloudflare panel. Now they need to be migrated to GitHub. The new version's deployment GitHub Action will automatically upload them to Cloudflare, so you no longer need to configure these environment variables in the Cloudflare panel.

‎docs/en/guide/contribution.md

+105
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# Contribute to Rin
2+
3+
We are happy to accept your patches and contributions to this project. You just need to follow some small guidelines.
4+
5+
## Commit-msg hooks
6+
7+
We have a sample commit-msg hook in `scripts/commit-msg.sh`. Please run the following command to set it up:
8+
9+
```sh
10+
ln -s ../../scripts/commit-msg.sh commit-msg
11+
```
12+
13+
On Windows, copy the `commit-msg.sh` file directly to `.git/hooks/commit-msg`.
14+
15+
```powershell
16+
cp .\scripts\commit-msg.sh .\.git\hooks\commit-msg
17+
```
18+
19+
This will run the following checks before each commit:
20+
21+
1. `tsc` Checks the code for syntax errors and unused variables and references.
22+
2. check that the commit message starts with one of the following: feature|chore|fix|docs|ci|style|test|pref
23+
24+
If you want to skip the hook, run `git commit` with the `--no-verify` option.
25+
26+
## Setting up your development environment
27+
28+
1. Fork & Clone the repository
29+
30+
2. Install [Node](https://nodejs.org/en/download/package-manager) & [Bun](https://bun.sh/)
31+
32+
3. Install dependencies
33+
```sh
34+
bun i
35+
```
36+
37+
4. Copy the `wrangler.example.toml` file to `wrangler.toml` and fill in the necessary information
38+
39+
:::tip
40+
Normally, you only need to fill in the `database_name` and `database_id` fields.\
41+
S3 configuration is not required, but if you want to use the image upload feature, you need to fill in the S3
42+
configuration.
43+
:::
44+
45+
5. Copy the `client/.env.example` file to `client/.env` and change the necessary configuration.
46+
47+
:::tip
48+
Typically, you only need to fill in `AVATAR`, `NAME` and `DESCRIPTION`.
49+
:::
50+
51+
6. Perform the database migration
52+
53+
:::tip
54+
If your database name (`database_name` in `wrangler.toml`) is not `rin`\
55+
Please modify the `DB_NAME` field in `scripts/dev-migrator.sh` before performing the migration
56+
:::
57+
```sh
58+
bun m
59+
```
60+
61+
7. Configuring the `.dev.vars' file
62+
Copy `.dev.example.vars` to `.dev.vars` and fill in the required information
63+
64+
:::tip
65+
Typically, you need to fill in the `RIN_GITHUB_CLIENT_ID` and `RIN_GITHUB_CLIENT_SECRET` as well as
66+
the `JWT_SECRET` fields.
67+
In the development environment, you need to create a separate GitHub OAuth service with a callback address
68+
of `http://localhost:11498/user/github/callback` \
69+
If you have changed the listening port of the server manually, please also change the port number in the callback
70+
address.
71+
:::
72+
73+
8. Start the development server
74+
```sh
75+
bun dev
76+
```
77+
78+
9. For better control of the development server, you can run the client and server dev commands in two separate
79+
terminals:
80+
```sh
81+
# tty1
82+
bun dev:client
83+
84+
# tty2
85+
bun dev:server
86+
```
87+
88+
## Committing Changes
89+
90+
1. for simple patches, they can usually be reviewed within 10 minutes during the day in the UTC+8 time zone. 2.
91+
92+
2. Do not force push minor changes after the PR is ready for review. Doing so forces maintainers to re-read your entire
93+
PR, which delays the review process. 3.
94+
95+
3. Always keep the CI green.
96+
97+
4. If the CI fails on your PR, do not push it. Even if you don't think it's the patch's fault. If something else is
98+
breaking the CI, help fix the root cause before you push.
99+
100+
*Start writing code happily!*
101+
102+
## Code review
103+
104+
All commits, including those from project members, need to be reviewed. We use GitHub pull requests for this purpose.
105+
For more information on using pull requests, see the GitHub Help.

0 commit comments

Comments
 (0)