zk
e363bd2532
* docs: migrate from mkdocs to mdbook - Rename old mkdocs docs/ to old-docs/ for reference - Set up new docs/ with mdbook (book.toml + src/ tree) - Mirror full nav structure from mkdocs.yml into SUMMARY.md - Add Justfile-docs with docs-serve, docs-build, docs-check, docs-install recipes - Import Justfile-docs from root Justfile - Rewrite .github/workflows/docs.yml: build step uses taiki-e/install-action to install mdbook, split into separate build + deploy jobs, PR builds run the check step too * ci(docs): pin actions to SHAs, install mdbook via release binary * ci(docs): install mdbook from apt instead of curling a release binary * dev: replace mkdocs python stack with mdbook in dev image * ci(docs): apt only works on Debian; restore release binary install for Ubuntu CI * docs: fix duplicate file entries in SUMMARY.md * docs: remove docs-install recipe * docs: remove site-url from book.toml to fix asset loading * dev: install mdbook from upstream release binary, not Debian apt The Debian package (0.4.x+ds) strips bundled font assets, leaving the built site without fonts/fonts.css. Use the upstream tarball (same as CI) so the theme is complete. Handles x86_64 and aarch64. * docs: vendor mdbook tarballs in dev/mdbook/, install from there Dockerfile.dev uses COPY + tar to install the right arch at build time. CI extracts the x86_64 tarball directly from the checkout. No network access required for either — and no stripped-fonts Debian package. * fix: unwritten
5.9 KiB
Setting up a Local Development Environment
Before you can contribute to Tachi, it'll help to have a functional setup on your machine.
You don't necessarily need to have a working install to contribute - you could easily make documentation contributions without having anything running on your machine - but it's extremely helpful to be able to run Tachi's things while working on them.
0. Install the basics
VSCode
We'll need a code editor so we can actually edit Tachi's code.
Please install VSCode. We'll use this as our editor because of it's excellent support for dev containers.
Terminal
You'll also need a terminal to run commands in. For Linux and Mac users, you can just open a Terminal app.
However, for Windows users we recommend installing the Windows Terminal.
With a terminal open you can proceed to the next steps!
Git
You'll need git to clone Tachi to your machine.
=== "Windows" Install git from the official website.
=== "Ubuntu, Debian"
Open a terminal and type this:
sh sudo apt install git
=== "Arch, Manjaro" Open a terminal and type this:
```sh
sudo pacman -S git
```
=== "MacOS" Open a terminal and type this:
```sh
brew install git
```
1. Getting Docker.
To set everything else up for local development, we'll use Docker.
=== "Windows, WSL Ubuntu" You should install Docker Desktop instead. Docker doesn't work well inside WSL.
=== "Debian" Please use the official Docker install guide.
=== "Ubuntu" Please use the official Docker install guide.
=== "Arch, Manjaro" Open a terminal and type this:
```sh
sudo pacman -S docker docker-compose
```
=== "MacOS" Open a terminal and type this:
```sh
brew install docker docker-compose
```
!!! info Docker is like a VM1 . It runs an entire Linux box to contain your software in, and generally sidesteps the whole "works on some machines" problem.
2. Fork and pull the repo.
Since you can't just commit straight to someone else's codebase (that would be a massive security issue), you need to make a fork of Tachi - One owned by you!
Go to the Tachi repository and click the Fork button in the top right (Make sure you're signed in).
Now, back to the terminal:
!!! tip It's good organisation to make a folder on your PC for codestuffs. If you do that, make sure you open the terminal in that folder, so your Tachi repo will save there!
Open a terminal and type the following commands:
# This will create a folder called Tachi on your PC.
# It'll create it wherever your terminal is currently open in.
git clone https://github.com/YOUR_GITHUB_USERNAME/Tachi
# Open this repository in VSCode!
code Tachi
3. Get into the container.
What is a container?
Your personal machine could be running anything. Windows, Mac, Linux, whatever! Tachi expects to be running on Linux and with specific versions of certain software running. It's a huge pain to ask you to install that software and manage it yourself. Plus, subtle differences between Windows and Linux cause problems all the time.
As such, we work inside a docker container. This is sort of like having a Linux VM with everything set up perfectly for you. I've spent quite a bit of time making this container user friendly, and it has so many nice things pre-installed for you.
Perhaps more importantly, the container has everything needed to run Tachi perfectly. Neat!
Getting into it
With VSCode open to Tachi, install the Dev Container extension.
Then, hit Ctrl+Shift+P to view all commands, and run Dev Containers: Rebuild and Reopen in Container.
!!! warning First time setup can take a very long time. This depends on the performance of your machine, and whether you're using Windows or not.
You can click `view log` in the bottom right to see the progress of making the container.
Working in the container
You want to do ALL your work inside the container. Doing thing outside of the container will cause issues or crashes.
There is a subtle confusing trick here. We now want to use a terminal inside our container. Do not use a terminal outside of VSCode now.
To open a terminal inside VSCode, use Ctrl+J to open the bottom panel.
Inside there there should be a TERMINAL tab, click that.
There should be a + at the top right of the panel. Click that to open a new terminal!
You should see a message starting with Welcome to Tachi!. Inside this shell, you have full access to Tachi and all of its utilities.
4. Authenticate with Github.
You'll need to authenticate with GitHub before you can actually push changes back to your repository.
Type gh auth login and follow the instructions.
You should now be properly authenticated!
5. Start Tachi!
With a terminal open inside the Tachi container you just cloned, run just start.
The frontend will be running on http://localhost:3000.
The backend listens on http://localhost:8080, and the Vite dev server proxies /api and /ir there so the browser talks to the app on port 3000 only (same-origin HTTP, no self-signed certificates).
!!! tip
Type just in the terminal to see other available commands.
Navigate to http://localhost:3000 and check your Tachi instance!
6. OK, Now what.
Now that you've got a working version of Tachi running on your local PC, you should go check out the component-specific contribution guides!
-
Docker is not actually a VM, it's significantly smarter and does some Linux jail cgroup nonsense. All you need to care about is that we're using it to spawn Linux VMs on your host system. ↩︎