summaryrefslogtreecommitdiffstats
path: root/README.md
blob: ebca2c448c01e31ee9493c8ecd678964c0b8b25b (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
# Self-hosting Wolfree instances with Docker Engine

This guide provides a step-by-step procedure for self-hosting Wolfree. You will use Docker CLI to interact with the Docker daemon through a terminal emulator. Docker Engine automates the execution of the static site generator and running the web server.

## How to self-host Wolfree

To self-host a mirror site of Wolfree instances using Docker Engine, follow these steps:

1. Install a terminal emulator. If you are unfamiliar with terminal emulators, refer to the "[Command line crash course](https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Understanding_client-side_tools/Command_line)" for guidance.

2. Install [Git](https://git-scm.com/) and [Docker Engine](https://docs.docker.com/).

3. Download the source code by executing one of the following commands. Each command will download the source code from a different web server. If one of the commands fails, try the next one until the download succeeds.

   ```shell
   git clone https://gitea.com/wolfree/wolfree-dockerfile.git
   ```

   ```shell
   git clone https://try.gitea.io/wolfree/wolfree-dockerfile.git
   ```

   ```shell
   git clone https://codeberg.org/wolfree/wolfree-dockerfile.git
   ```

   ```shell
   git clone https://git.disroot.org/wolfree/wolfree-dockerfile.git
   ```

   ```shell
   git clone https://next.forgejo.org/wolfree/wolfree-dockerfile.git
   ```

   ```shell
   git clone https://git.kiwifarms.net/wolfree/wolfree-dockerfile.git
   ```

   ```shell
   git clone http://it7otdanqu7ktntxzm427cba6i53w6wlanlh23v5i3siqmos47pzhvyd.onion/wolfree/wolfree-dockerfile.git
   ```

   Reference: [git clone](https://git-scm.com/docs/git-clone)

4. Wait until Git outputs the resolving message similar to the following:

   ```shell
   Receiving objects: 100% (100/100), 1.00 KiB | 1.00 KiB/s, done.
   Resolving deltas: 100% (100/100), done.
   ```

5. Build a Docker image by executing the following command:

   ```shell
   docker build --progress=plain --tag wolfree wolfree-dockerfile
   ```

   This command will generate the website using a static site generator.

   Reference: [docker build](https://docs.docker.com/engine/reference/commandline/build/)

6. Wait until Docker Engine outputs the exporting message similar to the following:

   ```shell
   #35 exporting to image
   #35 exporting layers done
   #35 writing image sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef done
   #35 naming to docker.io/library/wolfree done
   #35 DONE 0.0s
   ```

7. Run a Docker container by executing the following command:

   ```shell
   docker run --publish 80:80 wolfree
   ```

   This command will host the website using a web server.

   Reference: [docker run](https://docs.docker.com/engine/reference/commandline/run/)

8. Wait until the web server outputs the success message similar to the following:

   ```shell
   > docusaurus@0.0.0 serve
   > docusaurus serve --host localhost --port 80

   [SUCCESS] Serving "build" directory at: http://localhost:80/
   ```

9. Access the mirror site locally on the same computer where the Docker container runs. Open a web browser and navigate to [http://localhost/](http://localhost/).

10. On the home page of the mirror site, enter a math problem in the text box and click the submit button.

Congratulations! You have successfully self-hosted Wolfree.

## How to self-host Libredirect-compatible instances

By default, Wolfree instances are paywall-bypassing and incompatible with Libredirect. To make them Libredirect-compatible and respect paywalls, follow these steps:

1. Install [Git](https://git-scm.com/) and [Docker Engine](https://docs.docker.com/).

2. Download the source code with Git:

   ```shell
   git clone https://gitea.com/wolfree/wolfree-dockerfile.git
   git clone https://try.gitea.io/wolfree/wolfree-dockerfile.git
   git clone https://codeberg.org/wolfree/wolfree-dockerfile.git
   git clone https://git.disroot.org/wolfree/wolfree-dockerfile.git
   git clone https://next.forgejo.org/wolfree/wolfree-dockerfile.git
   git clone https://git.kiwifarms.net/wolfree/wolfree-dockerfile.git
   git clone http://it7otdanqu7ktntxzm427cba6i53w6wlanlh23v5i3siqmos47pzhvyd.onion/wolfree/wolfree-dockerfile.git
   ```

3. Open the following file with a text editor:

   `rust/wolfree_patch_libredirect/src/main.rs`

4. Remove the line containing the `return` keyword. Save the change. The changed code should look like this:

   ```rust
   // Remove the following line to make the instances Libredirect-compatible.
   // Remove the previous line to make the instances Libredirect-compatible.
   ```

5. Build the image and run the container with Docker Engine:

   ```shell
   docker build --progress=plain --tag wolfree wolfree-dockerfile
   docker run --publish 80:80 wolfree
   ```

6. Browse [http://localhost/](http://localhost/). Your instances should have become Libredirect-compatible and respect paywalls. If they remain paywall-bypassing and incompatible with Libredirect, please report the problem in the issue trackers of the repositories.

## Troubleshooting dependency graphs

To regenerate `docusaurus/package.json`, follow these steps:

1. Install [NPM](https://docs.npmjs.com/).

2. Initialize a Docusaurus project with the classic template and the TypeScript variant:

   ```shell
   npm --yes -- init docusaurus docusaurus classic . --typescript
   ```

3. Install MUI, a React component library:

   ```shell
   npm --prefix ./docusaurus/ -- install @mui/material @emotion/react @emotion/styled
   ```

## Glossary of file extensions

- `.md`/`.mdx`: [MarkDown XML](https://mdxjs.com/docs/)
- `.js`/`.jsx`: [JavaScript XML](https://react.dev/learn/writing-markup-with-jsx)
- `.ts`/`.tsx`: [TypeScript XML](https://www.typescriptlang.org/docs/handbook/jsx.html)
- `.rs`: [Rust Programming Language](https://www.rust-lang.org/learn)

## Helpful resources for new developers

If you're new to web development, here are some websites and tools to get you started:

- [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Learn): A comprehensive resource for web developers, offering guides, tutorials, and references for various web technologies.

- [Chrome DevTools - Chrome Developers](https://developer.chrome.com/docs/devtools/): A set of web developer tools built directly into the Google Chrome browser, providing practical features to inspect and debug web applications.

- [TypeScript: JavaScript With Syntax For Types.](https://www.typescriptlang.org/): A strongly typed programming language that builds on JavaScript, giving you better tooling at any scale.

- [Web.Dev](https://web.dev/learn/): A learning platform by Google that offers web development courses, providing practical examples to help you improve your skills.

- [Desktop/PC - Privacy Guides](https://www.privacyguides.org/en/desktop/): A list of recommended Linux distributions with powerful terminal emulators pre-installed by default, empowering you with automating deployment, scaling, and management of containerized applications.

These resources will help you get started. Happy learning!

## UX writing tips

- [Style guide: UX writing best practices](https://m3.material.io/foundations/content-design/style-guide/ux-writing-best-practices): Writing UI text that anyone can understand.

- [UX writing: study guide](https://www.nngroup.com/articles/ux-writing-study-guide/): How to write and present information that aligns with users' needs and online reading behaviors.

- [UX basics: study guide](https://www.nngroup.com/articles/ux-basics-study-guide/): The basics of user experience.

- [Web UX: study guide](https://www.nngroup.com/articles/web-ux-study-guide/): How users interact with the web and how to design web user experiences.

## License

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.