diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 186 |
1 files changed, 120 insertions, 66 deletions
@@ -1,75 +1,109 @@ -# Wolfree Dockerfile: Self-Host a Mirror Site of Wolfree Instances +# Self-hosting Wolfree instances with Docker Engine -This repository provides a Dockerfile and instructions for self-hosting a mirror site of Wolfree instances. +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. -Follow the instructions below to control Docker through terminal emulators. Docker will automatically execute the static site generator and run the web server. +## How to self-host Wolfree -## Prerequisites +To self-host a mirror site of Wolfree instances using Docker Engine, follow these steps: -Before getting started, make sure you have the following prerequisites installed on your computer: +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. -1. **Terminal Emulator**: If you are unfamiliar with terminal emulators, you can learn how to use them in [Command Line Crash Course - Learn Web Development | MDN](https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Understanding_client-side_tools/Command_line). +2. Install [Git](https://git-scm.com/) and [Docker Engine](https://docs.docker.com/). -2. **Docker**: If you don't have Docker installed, download it from [docker.com](https://www.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. -## Instructions + ```shell + git clone https://gitea.com/wolfree/wolfree-dockerfile.git + ``` -Follow the steps below to self-host a mirror site of Wolfree instances: + ```shell + git clone https://try.gitea.io/wolfree/wolfree-dockerfile.git + ``` -1. **Build the Docker Image**: + ```shell + git clone https://codeberg.org/wolfree/wolfree-dockerfile.git + ``` - Open your terminal emulator and execute one of the following commands to build the Docker image. Each command downloads the source code from a different web server. If one of the commands fails, try the next one in the list until the build succeeds. + ```shell + git clone https://git.disroot.org/wolfree/wolfree-dockerfile.git + ``` ```shell - docker build -t wolfree https://try.gitea.io/wolfree/wolfree-dockerfile.git - docker build -t wolfree https://codeberg.org/wolfree/wolfree-dockerfile.git - docker build -t wolfree https://git.disroot.org/wolfree/wolfree-dockerfile.git - docker build -t wolfree https://next.forgejo.org/wolfree/wolfree-dockerfile.git - docker build -t wolfree https://git.kiwifarms.net/wolfree/wolfree-dockerfile.git - docker build -t wolfree http://it7otdanqu7ktntxzm427cba6i53w6wlanlh23v5i3siqmos47pzhvyd.onion/wolfree/wolfree-dockerfile.git + git clone https://next.forgejo.org/wolfree/wolfree-dockerfile.git ``` -2. **Run the Docker Container**: + ```shell + git clone https://git.kiwifarms.net/wolfree/wolfree-dockerfile.git + ``` + + ```shell + git clone http://it7otdanqu7ktntxzm427cba6i53w6wlanlh23v5i3siqmos47pzhvyd.onion/wolfree/wolfree-dockerfile.git + ``` - Execute the following command in your terminal emulator to run the Docker container: + 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 run -p 80:80 wolfree + docker build --progress=plain --tag wolfree wolfree-dockerfile ``` -3. **Wait for Success Messages**: + This command will generate the website using a static site generator. + + Reference: [docker build](https://docs.docker.com/engine/reference/commandline/build/) - Wait until Docker outputs success messages similar to the following: +6. Wait until Docker Engine outputs the exporting message similar to the following: ```shell - > docusaurus@0.0.0 serve - > docusaurus serve --port 80 --host localhost + #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 + ``` - [SUCCESS] Serving "build" directory at: http://localhost:80/ +7. Run a Docker container by executing the following command: + + ```shell + docker run --publish 80:80 wolfree ``` -4. **Access Your Mirror Site**: + This command will host the website using a web server. + + Reference: [docker run](https://docs.docker.com/engine/reference/commandline/run/) - You can access your mirror site locally on the same computer where the Docker container runs. Open a web browser, navigate to [http://localhost/](http://localhost/) to access your mirror site, and enter math problems in the text box. +8. Wait until the web server outputs the success message similar to the following: -Congratulations! You have successfully self-hosted a mirror site of Wolfree instances. + ```shell + > docusaurus@0.0.0 serve + > docusaurus serve --host localhost --port 80 + + [SUCCESS] Serving "build" directory at: http://localhost:80/ + ``` -## Local Development +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/). -If you wish to contribute to the development of Wolfree instances, follow these steps: +10. On the home page of the mirror site, enter a math problem in the text box and click the submit button. -1. **Prepare the Development Environment**: +Congratulations! You have successfully self-hosted Wolfree. - Install Git and Docker on your local machine. You can download them from the following official websites: +## How to self-host Libredirect-compatible instances - - [Git Official Website](https://git-scm.com/) - - [Docker Official Website](https://www.docker.com/) +By default, Wolfree instances are paywall-bypassing and incompatible with Libredirect. To make them Libredirect-compatible and respect paywalls, follow these steps: -2. **Clone the Repository**: +1. Install [Git](https://git-scm.com/) and [Docker Engine](https://docs.docker.com/). - Run one of the following commands to clone the repository from one of the Gitea and Forgejo servers: +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 @@ -78,60 +112,80 @@ If you wish to contribute to the development of Wolfree instances, follow these git clone http://it7otdanqu7ktntxzm427cba6i53w6wlanlh23v5i3siqmos47pzhvyd.onion/wolfree/wolfree-dockerfile.git ``` -3. **Run the Docker Container**: +3. Open the following file with a text editor: - After cloning the repository, navigate to the project directory: + `rust/wolfree_patch_libredirect/src/main.rs` - ```shell - cd wolfree-dockerfile +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. ``` - Then, run the following commands to build the image and run the container: +5. Build the image and run the container with Docker Engine: ```shell - docker build --tag wolfree --progress=plain . - docker run --publish 80:80 --rm wolfree + docker build --progress=plain --tag wolfree wolfree-dockerfile + docker run --publish 80:80 wolfree ``` -## Configuring Wolfree Instances for LibRedirect +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 configure Wolfree instances to integrate with LibRedirect, follow these steps: +To regenerate `docusaurus/package.json`, follow these steps: -1. Clone the Git repository and open the Dockerfile in a text editor. +1. Install [NPM](https://docs.npmjs.com/). -2. In the Dockerfile, remove the number sign (#) at the beginning of the `RUN` command. After removing the number sign, the `RUN` command should look like this: +2. Initialize a Docusaurus project with the classic template and the TypeScript variant: - ```dockerfile - # Optionally, customize Wolfree instances to suit LibRedirect. - # https://github.com/libredirect/browser_extension/issues/425 - # To integrate Wolfree with LibRedirect, please delete the number sign at the beginning of the following line. - RUN PATH="$HOME/.cargo/bin:$PATH" cargo run --manifest-path ./rust/wolfree_libredirect_patch/Cargo.toml -- ; + ```shell + npm --yes -- init docusaurus docusaurus classic . --typescript ``` -3. Build a Docker image and run a container. +3. Install MUI, a React component library: -## Helpful Resources for New Developers + ```shell + npm --prefix ./docusaurus/ -- install @mui/material @emotion/react @emotion/styled + ``` -If you're new to web development, here are some helpful websites and tools to get you started: +## Glossary of file extensions -- [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Learn): MDN is a comprehensive resource for web developers. It offers guides, tutorials, and references for various web technologies. It's a great place to learn and explore web development concepts. +- `.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) -- [Web Dev](https://web.dev/learn/): Web Dev is a learning platform by Google that offers web development courses. It provides practical examples to help you improve your skills. +## Helpful resources for new developers -- [Chrome DevTools - Chrome Developers](https://developer.chrome.com/docs/devtools/): Chrome DevTools is a set of web developer tools built directly into the Google Chrome browser. It provides powerful features to inspect and debug web applications. +If you're new to web development, here are some websites and tools to get you started: -- [TypeScript: JavaScript With Syntax For Types.](https://www.typescriptlang.org/): TypeScript is a strongly typed programming language that builds on JavaScript, giving you better tooling at any scale. +- [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. -- [Writing Markup with JSX – React](https://react.dev/learn/writing-markup-with-jsx): JSX is a syntax extension for JavaScript that allows you to write HTML-like markup inside a JavaScript file. +- [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. -- [Markdown for the component era | MDX](https://mdxjs.com/docs/): MDX is a format that combines markdown, JSX, JavaScript expressions, and import/export statements in JavaScript modules. +- [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. -- [Desktop/PC - Privacy Guides](https://www.privacyguides.org/en/desktop/): Most Linux distributions have a terminal available by default. You can check out this guide for recommended distributions. +- [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. -These resources will help you get started and enhance your skills as a web developer. Happy learning! +- [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. -## License +These resources will help you get started. Happy learning! -SPDX-License-Identifier: AGPL-3.0-or-later +## 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. +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. |