diff --git a/README.md b/README.md index 258bfa16f..d608cada4 100644 --- a/README.md +++ b/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 git@github.com: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 diff --git a/docs/DEVELOPER-linux.md b/docs/DEVELOPER-linux.md new file mode 100644 index 000000000..2bf3e4713 --- /dev/null +++ b/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 git@github.com: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. diff --git a/docs/DEVELOPER-osx.md b/docs/DEVELOPER-osx.md new file mode 100644 index 000000000..b5afce02d --- /dev/null +++ b/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 git@github.com: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 diff --git a/docs/DEVELOPER-win.md b/docs/DEVELOPER-win.md new file mode 100644 index 000000000..39fbb9964 --- /dev/null +++ b/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 +```