diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 4ceda02..2b91ca0 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -1,36 +1,31 @@ // For format details, see https://aka.ms/devcontainer.json. For config options, see the // README at: https://github.com/devcontainers/templates/tree/main/src/javascript-node-postgres { - "name": "MakeUC Website", - "dockerComposeFile": "docker-compose.yml", - "service": "app", - "workspaceFolder": "/workspace", - // Features to add to the dev container. More info: https://containers.dev/features. - // "features": {}, - "forwardPorts": [ - 3000, - 5432, - 9090, - 9091 - ], - "initializeCommand": "[ -f .devcontainer/.env.local ] && echo 'A local environment file already exists.' || cp .devcontainer/.env.local.default .devcontainer/.env.local", - "postCreateCommand": "yarn install", - "customizations": { - "vscode": { - "extensions": [ - "aaron-bond.better-comments", - "bradlc.vscode-tailwindcss", - "csstools.postcss", - "dbaeumer.vscode-eslint", - "eamodio.gitlens", - "Gruntfuggly.todo-tree", - "GraphQL.vscode-graphql", - "Prisma.prisma", - "stylelint.vscode-stylelint", - "VisualStudioExptTeam.vscodeintellicode" - ] - } - } - // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root. - // "remoteUser": "root" + "name": "MakeUC Website", + "dockerComposeFile": "docker-compose.yml", + "service": "app", + "workspaceFolder": "/workspace", + // Features to add to the dev container. More info: https://containers.dev/features. + // "features": {}, + "forwardPorts": [3000, 5432, 9090, 9091], + "initializeCommand": "node .devcontainer/setup.js", + "postCreateCommand": "yarn install", + "customizations": { + "vscode": { + "extensions": [ + "aaron-bond.better-comments", + "bradlc.vscode-tailwindcss", + "csstools.postcss", + "dbaeumer.vscode-eslint", + "eamodio.gitlens", + "Gruntfuggly.todo-tree", + "GraphQL.vscode-graphql", + "Prisma.prisma", + "stylelint.vscode-stylelint", + "VisualStudioExptTeam.vscodeintellicode" + ] + } + } + // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root. + // "remoteUser": "root" } diff --git a/.devcontainer/setup.js b/.devcontainer/setup.js new file mode 100644 index 0000000..e84a7f8 --- /dev/null +++ b/.devcontainer/setup.js @@ -0,0 +1,8 @@ +const fs = require("fs"); +const dest = ".devcontainer/.env.local"; +if (!fs.existsSync(dest)) { + fs.copyFileSync(".devcontainer/.env.local.default", dest); + console.log("Copied default environment file."); +} else { + console.log("A local environment file already exists."); +} diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 8cc93c7..9e883c9 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,14 +1,8 @@ -# Rai's Monkeypatched Developemnt Setup Guide - -note, this is outdated a bit since some issues with workarounds listed here have been fixed! (ex, discord env variable requirement) - -Basically, I'll detail how I set up the repository (only the client for now, but will update) in painful details so hopefully you can get the site ready for local development. This is completely objective and based on my personal experience setting up the site, so things might change, and other debugging stuff might and will get added as I get more user stories in. - ## Setup ### Environment Variables -The backend of this project requires usage of environmental variables to access the database and the Discord bot. Make sure to contact with your Technical Lead to obtain these credentials if your task is to mess with the backend in any capacity. +The backend of this project requires usage of environment variables to access the database and the Discord bot. Make sure to contact with your Technical Lead to obtain these credentials if your task is to mess with the backend in any capacity. Specifically, after obtaining these credentials, navigate to `/.devcontainer` and create a file called `.env.local`. Then, copy the fields from `.env.local.default` to this new file and fill in the missing credentials. @@ -26,7 +20,7 @@ You should open a new Codespace from the `main` branch. On creation, GitHub will #### Common Setup Steps -1. Have [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed (or Rancher Desktop, if you managed to get it working with VSCode). Also have [yarn](https://yarnpkg.com/getting-started/install) installed. +1. Have [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed (or Rancher Desktop, if you managed to get it working with VSCode). Also have [Node.js](https://nodejs.org/) and [yarn](https://yarnpkg.com/getting-started/install) installed. 2. Clone the repository and open the repository in VSCode. 3. Make sure that you have the `Dev Container` extension installed in VSCode. Then open the command pallet for VSCode with `F1` or `CTRL+SHIFT+P` and run `Dev Containers: Reopen in Container`. 4. Open the terminal inside VSCode (the one that is spawned from the container) and run `yarn install`. @@ -40,19 +34,25 @@ To push, a pre-push hook is run. Inside this hook, `yarn build` is executed. To If the build fails, particularly on the client, a cached build may have been used and this cache is not being invalidated (especially if no changes to the server have been made). To invalidate said cached build, remove the `.next` folder in the client directory. -#### Windows 10 Known Bugs +#### Dev Container & Docker Troubleshooting -- In the devcontainer setup, there is a command that is ran before container setup that _expects_ a Linux environment (it is written in bash). This will fail the setup step for Windows users since Powershell cannot run bash commands. This command basically checks whether an `.env.local` already exist, and if not, create a copy of the `.env.local.default` and rename it to `.env.local`. One of the ways to monkeypatch this issue is to delete the `"initializeCommand"` field in the `/.devcontainer/.devcontainer.json`, and create the `.env.local` yourself and copy in the content of the `.env.local.default` file. +If Dev Containers fail to start, check the "Terminal" tab in VS Code. If it's a Docker build error, you may need to scroll up through the logs to find the root cause. -- If you get an error related to `docker-credential-wincred`, _restart your laptop_. This error seems to be from the fact that some docker executable are not added to the Windows PATH yet. If you reset and this still doesn't work, log into your Docker account (create one on the Docker website) with `docker login`. I doubt that would work, but I am logged in, so do that too just in case. +- **`request returned 500 Internal Server Error for API route and version http://%2FUsers.../v1.52/version` (Mac/Linux):** + This means the Docker Daemon crashed or hung locally. + _Fix:_ Quit Docker Desktop, force quit any remaining "Docker" processes in Activity Monitor / System Monitor, and restart Docker Desktop. Wait until "Engine Running" appears, then try again. -#### WSL Known Bugs +- **`mkdir: can't create directory...: No space left on device` or `tar: write error: No space left on device`:** + Your Docker virtual disk or physical hard drive is 100% full. Because it's full, Docker cannot install the VS Code Remote Server into the container. + _Fix:_ Free up space on your physical hard drive. If you have space on your computer but Docker is still full, run `docker system prune -a --volumes` in your terminal to clear out unused Docker data. -- Docker daemon not working. I've encountered this bug a while ago (like 2023) with Docker Desktop. Basically, Docker Desktop cannot tunnel to WSL and give it access to Docker. I believe Rancher Desktop plays nicer with WSL, so use that instead. Otherwise, look up how to tunnel Docker to WSL with Docker Desktop/Rancher Desktop. You can check whether Docker is accessible within WSL by running `docker --version` inside WSL and see if the command executes. +- **`OCI runtime create failed: runc create failed... namespace path: lstat /proc/.../ns/net: no such file or directory` (Windows):** + This happens when a Linux namespace (which Docker uses for networking) gets corrupted inside the WSL 2 VM (often due to computer sleep or unclean shutdown). + _Fix:_ Open PowerShell as Administrator and run `wsl --shutdown`. Wait 10 seconds for it to fully stop, restart Docker Desktop, and try opening the dev container again. -#### Linux Known Bugs +#### Windows 10 Known Bugs -#### Mac Known Bugs +- If you get an error related to `docker-credential-wincred`, _restart your laptop_. This error seems to be from the fact that some docker executable are not added to the Windows PATH yet. If you reset and this still doesn't work, log into your Docker account (create one on the Docker website) with `docker login`. I doubt that would work, but I am logged in, so do that too just in case. ## Development diff --git a/README.md b/README.md index 5e74b0e..f9ee91e 100644 --- a/README.md +++ b/README.md @@ -27,10 +27,7 @@ Refer to each folder's README for details on working with that part of the codeb ## Getting Started -Note that yarn and a container engine are required for this project. - -**If you are using Windows as your main environment, WSL is _strongly_ recommended as using the devcontainer is very inconsistent on just Windows.** -**This means to use the `code .` command in WSL. You can read more [here](https://code.visualstudio.com/docs/remote/wsl).** +Note that Node.js, yarn, and a container engine are required for this project. For a container engine, one of the following is recommended: