Split developer docs into per-OS files

README.md

@@ -17,48 +17,11 @@ There are some exceptions:
 
 ## Development
 
-### Prerequisites
- * docker and compose
-   * enable Kubernetes in the Docker Desktop settings
-
-### Setup
- * install [Taskfile](https://taskfile.dev/installation/)
-   * windows: `winget install Task.Task`
-   * linux: `sudo snap install task --classic` or other options on their website
-   * mac: `brew install go-task/tap/go-task`
-   * via npm: `npm install -g @go-task/cli`
- * install [Tilt](https://docs.tilt.dev/) and add it to your path (don't forget to read the script before running it)
-   * on Linux, the script will install tilt into `$HOME/.local/bin`, creating it if it doesn't exist
-     * most Linux distributions put `$HOME/.local/bin` in your PATH automatically. If `tilt version` doesn't work, log out and log back in and it should work; otherwise you'll need to add it to your PATH in `$HOME/.bashrc` or equivalent.
-   * on Windows, the Tilt installer will create a `bin` folder in your home folder and put the Tilt binary there
-     * you will then need to do the following to make sure the Tilt binary is in your PATH:
-     * go to your System properties, click the **Advanced** tab, and click **Environment Variables...**
-     * Click the Path variable (in either User or System, User is recommended) and click the **Edit...** button
-     * Add `C:\Users\YOUR_USER_NAME\bin` to the list (if it's not already there) and click **OK**
- * run `tilt version` to check that Tilt is installed correctly
- * clone the repo
- * run `git push` to make sure your GitHub credentials are set up
-   * on Windows, allow the Git Credential Manager to log in to GitHub via your browser
-   * on Linux, upload your SSH key to your GitHub account if you haven't done so already, then run `git remote set-url --push origin [email protected]:sillsdev/languageforge-lexbox`
- * on Windows, open PowerShell and run `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned`
-   * this is necessary before running `task setup` below, which uses a PowerShell script to download seed data
- * run `task setup`, which:
-   * initializes a local.env file
-   * tells Git to use our ignore revs file
-   * checks out Git submodules
-   * downloads the FLEx repo for the project seed data
-
-#### Extra setup steps for Windows
-
-If you're running Windows, you may need to add the following lines to your `C:\Windows\system32\drivers\etc\hosts` file:
+See the appropriate file for your operating system:
 
-```
-127.0.0.1 resumable.localhost
-127.0.0.1 hg.localhost
-127.0.0.1 admin.localhost
-```
-
-On Linux, anything with a `.localhost` domain is automatically mapped to 127.0.0.1 so you don't need to edit your `/etc/hosts` file.
+* [Windows](docs/DEVELOPER-win.md)
+* [Linux](docs/DEVELOPER-linux.md)
+* [Mac](docs/DEVELOPER-osx.md)
 
 ### Kubernetes workflow
 

docs/DEVELOPER-linux.md

@@ -0,0 +1,31 @@
+### Prerequisites
+  * [Docker Desktop for Linux](https://docs.docker.com/desktop/setup/install/linux/) (provides docker and compose)
+    * using native docker can lead to permissions issues with shared volumes, and some of our code (e.g. the Tiltfile) assumes you're running Docker Desktop
+    * enable Kubernetes in the Docker Desktop settings
+
+### Setup
+  * install [Taskfile](https://taskfile.dev/installation/)
+    * `sudo snap install task --classic` or other options on their website
+    * Or via npm: `npm install -g @go-task/cli`
+  * install [Tilt](https://docs.tilt.dev/) and add it to your path (don't forget to read the script before running it)
+    * the script will install tilt into `$HOME/.local/bin`, creating it if it doesn't exist
+      * most Linux distributions put `$HOME/.local/bin` in your PATH automatically
+      * if `tilt version` doesn't work, try running `source $HOME/.bashrc`, or log out and log back in
+  * run `tilt version` to check that Tilt is installed correctly
+  * clone the repo
+  * run `git push` to make sure your GitHub credentials are set up
+    * if it doesn't work, upload your SSH key to your GitHub account if you haven't done so already, then run `git remote set-url --push origin [email protected]:sillsdev/languageforge-lexbox`
+  * run `task setup`, which:
+    * initializes a local.env file
+    * tells Git to use our ignore revs file
+    * checks out Git submodules
+    * downloads the FLEx repo for the project seed data
+  * optional but recommended: turn off logging for Docker Desktop
+    * Docker Desktop's default is to log verbose messages to stderr, which by default gets sent to the systemd journal and/or /var/log/syslog
+    * This can result in your /var partition filling up fast (one developer saw his syslog grow by multiple gigabytes in a single week)
+    * To silence Docker Desktop logs, create the following drop-in at `$HOME/.config/systemd/user/docker-desktop.service.d/stop-log-spam.conf`:
+    ```
+    [Service]
+    StandardError=null
+    ```
+    * This file can be named anything as long as it ends in `.conf` and is in the correct directory, e.g. `override.conf` would work. The directory must be named exactly as shown.

docs/DEVELOPER-osx.md

@@ -0,0 +1,19 @@
+### Prerequisites
+  * docker and compose
+    * enable Kubernetes in the Docker Desktop settings
+
+### Setup
+  * install [Taskfile](https://taskfile.dev/installation/)
+    * `brew install go-task/tap/go-task` should do it
+    * Or via npm: `npm install -g @go-task/cli`
+  * install [Tilt](https://docs.tilt.dev/) and add it to your path (don't forget to read the script before running it)
+  * run `tilt version` to check that Tilt is installed correctly
+  * clone the repo
+  * run `git push` to make sure your GitHub credentials are set up
+    * allow the Git Credential Manager to log in to GitHub via your browser
+    * or upload your SSH key to your GitHub account if you haven't done so already, then run `git remote set-url --push origin [email protected]:sillsdev/languageforge-lexbox`
+  * run `task setup`, which:
+    * initializes a local.env file
+    * tells Git to use our ignore revs file
+    * checks out Git submodules
+    * downloads the FLEx repo for the project seed data

docs/DEVELOPER-win.md

@@ -0,0 +1,29 @@
+### Prerequisites
+  * docker and compose
+    * enable Kubernetes in the Docker Desktop settings
+
+### Setup
+  * install [Taskfile](https://taskfile.dev/installation/)
+    * `winget install Task.Task` should do it
+    * Or via npm: `npm install -g @go-task/cli`
+  * install [Tilt](https://docs.tilt.dev/) and add it to your path (don't forget to read the script before running it)
+    * the Tilt installer will create a `bin` folder in your home folder and put the Tilt binary there
+    * you may then need to add `C:\Users\YOUR_USER_NAME\bin` to your PATH
+  * run `tilt version` to check that Tilt is installed correctly
+  * clone the repo
+  * run `git push` to make sure your GitHub credentials are set up
+    * allow the Git Credential Manager to log in to GitHub via your browser
+  * open PowerShell and run `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned`
+    * this is necessary before running `task setup` below, which uses a PowerShell script to download seed data
+  * run `task setup`, which:
+    * initializes a local.env file
+    * tells Git to use our ignore revs file
+    * checks out Git submodules
+    * downloads the FLEx repo for the project seed data
+  * add the following lines to your `C:\Windows\system32\drivers\etc\hosts` file:
+
+```
+127.0.0.1 resumable.localhost
+127.0.0.1 hg.localhost
+127.0.0.1 admin.localhost
+```