docs: dev env setup and codespaces (#586)

.devcontainer/Dockerfile

@@ -18,13 +18,6 @@ gnupg2 \
 iputils-ping \
 net-tools \
 software-properties-common
-RUN curl -fsSL https://www.mongodb.org/static/pgp/server-7.0.asc | apt-key add -
-RUN echo "deb [ arch=amd64 ] https://repo.mongodb.org/apt/debian bullseye/mongodb-org/7.0 main" | tee /etc/apt/sources.list.d/mongodb-org-7.0.list
-RUN apt-get update
-RUN apt-get install -y \
-mongodb-org
-RUN sed -i "s,\\(^[[:blank:]]*bindIp:\\) .*,\\1 0.0.0.0," /etc/mongod.conf
-RUN sed -i "s,\\(^[[:blank:]]*dbPath:\\) .*,\\1 /workspaces/playnite-web/.mongodb/data," /etc/mongod.conf
 
 RUN apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF
 RUN echo "deb https://download.mono-project.com/repo/debian stable-buster main" > /etc/apt/sources.list.d/mono-official-stable.list

.devcontainer/devcontainer.json

@@ -9,7 +9,7 @@
       "version": "7.0.403"
     },
     "ghcr.io/devcontainers/features/node:1": {
-      "version": "20.9.0",
+      "version": "22.5.0",
       "nodeGypDependencies": true
     },
     "ghcr.io/devcontainers/features/powershell:1": {},
@@ -18,9 +18,6 @@
     }
   },
   "customizations": {
-    "devpod": {
-      "prebuildRepository": "ghcr.io/andrew-codes/playnite-web"
-    },
     "vscode": {
       "settings": {
         "terminal.integrated.profiles.linux": {
@@ -32,35 +29,49 @@
         "workbench.colorTheme": "Dracula Pro"
       },
       "extensions": [
+        "apollographql.vscode-apollo",
         "arcanis.vscode-zipfs",
         "bierner.github-markdown-preview",
         "bierner.markdown-yaml-preamble",
         "capaj.vscode-exports-autocomplete",
         "cmstead.js-codeformer",
         "cmstead.jsrefactor",
+        "codecov.codecov",
+        "DavidAnson.vscode-markdownlint",
         "dbaeumer.vscode-eslint",
         "dracula-theme-pro.theme-dracula-pro",
         "drKnoxy.eslint-disable-snippets",
         "eamodio.gitlens",
         "EditorConfig.EditorConfig",
         "esbenp.prettier-vscode",
+        "GitHub.codespaces",
         "GitHub.copilot-chat",
         "GitHub.copilot",
         "github.vscode-github-actions",
         "GitHub.vscode-pull-request-github",
+        "GraphQL.vscode-graphql-syntax",
         "GraphQL.vscode-graphql",
+        "hbenl.vscode-test-explorer-liveshare",
+        "hbenl.vscode-test-explorer",
         "johnuphoff.vscode-styled-sort",
         "kisstkondoros.vscode-codemetrics",
         "mikestead.dotenv",
+        "ms-azuretools.vscode-docker",
+        "ms-dotnettools.csdevkit",
+        "ms-dotnettools.csharp",
         "ms-vscode.powershell",
+        "ms-vsliveshare.vsliveshare",
         "Orta.vscode-jest",
         "paulmolluzzo.convert-css-in-js",
         "pflannery.vscode-versionlens",
         "redhat.vscode-xml",
         "redhat.vscode-yaml",
         "rpdswtk.vsmqtt",
         "sburg.vscode-javascript-booster",
+        "steoates.autoimport",
         "streetsidesoftware.code-spell-checker",
+        "styled-components.vscode-styled-components",
+        "Terrastruct.d2",
         "yzhang.markdown-all-in-one"
       ]
     }
@@ -75,4 +86,4 @@
   "containerEnv": {
     "DISPLAY": "localhost:0"
   }
-}
+}

.devcontainer/post-create.sh

@@ -7,33 +7,3 @@ echo -e "{
 /usr/local/share/docker-init.sh
 
 corepack enable
-corepack prepare --activate yarn@^4.0.0
-
-set -o allexport
-. $PWD/local.env
-set +o allexport
-
-mosquitto_passwd -b -c /etc/mosquitto/passwd $MQTT_USERNAME $MQTT_PASSWORD
-echo -e "allow_anonymous false
-password_file /etc/mosquitto/passwd
-listener 1883" >/etc/mosquitto/conf.d/default.conf
-mosquitto -c /etc/mosquitto/conf.d/default.conf --daemon --verbose
-
-mongoDataExists=$(ls .data/mongodb | wc -l)
-mkdir -p /.data/mongodb
-docker run --name playnite-web-db -d \
-  --network host \
-  -e MONGO_INITDB_ROOT_USERNAME=$MONGO_INITDB_ROOT_USERNAME \
-  -e MONGO_INITDB_ROOT_PASSWORD=$MONGO_INITDB_ROOT_PASSWORD \
-  -v $PWD/.data/mongodb:/data/db \
-  -v $PWD/.data/games:/data/backup/games \
-  mongo:7.0.3-jammy
-
-if [ $mongoDataExists -eq 0 ]; then
-  docker exec -t playnite-web-db mongorestore --nsInclude games.* /data/backup
-fi
-
-if [ $(ls apps/playnite-web/public/assets/asset-by-id/ | wc -l) -eq 0 ]; then
-  echo "Copying development environment game assets"
-  cp -r .data/asset-by-id/ apps/playnite-web/public/assets
-fi

.vscode/settings.json

@@ -39,5 +39,6 @@
   "jest.runMode": {
     "type": "on-demand",
     "deferred": true
-  }
-}
+  },
+  "dotnet.preferCSharpExtension": true
+}

README.md

@@ -18,6 +18,6 @@ Playnite Web offers:
 
 ## Getting Started
 
-1. [Install and run Playnite Web](./docs/guides/setup.md)
+1. [Install and run Playnite Web](./docs/documents/guides/setup.md)
 2. [Playnite Web API and other documentation](./docs/README.md)
-3. [Contributions](./docs/documents/CONTRIBUTING.md)
+3. [Contributions](./docs/documents/CONTRIBUTING.md) and [local development environment](./docs/documents/contributing/development-environment)

_docs/contributing/development-environment/codespaces.md

@@ -0,0 +1,22 @@
+# Developer Environment: Codespace
+
+## Required Software
+
+Install the following software on your local machine:
+
+1. [vscode](https://code.visualstudio.com/Download)
+2. XServer (for running Cypress tests in codespace).
+   - For OSX, recommend: [XQuartz](https://www.bing.com/ck/a?!&&p=c21da4f99329c03fJmltdHM9MTcxODg0MTYwMCZpZ3VpZD0zOTJjZTBlOC1iMzRjLTY3Y2MtMDU4NC1mM2NkYjI2MDY2NjUmaW5zaWQ9NTIyNw&ptn=3&ver=2&hsh=3&fclid=392ce0e8-b34c-67cc-0584-f3cdb2606665&psq=xquartz+&u=a1aHR0cHM6Ly93d3cueHF1YXJ0ei5vcmcv&ntb=1)
+   - For Windows, still need a recommendation.
+
+## Preparing Codebase
+
+1. [Fork the playnite-web repo](https://github.com/andrew-codes/playnite-web/fork)
+2. Ensure your XServer application is running on local machine.
+   - Ensure your XServer is configured to Authenticate and Allow Connections from network clients
+3. Start a codespace and open in vscode.
+4. Run `yarn`
+5. Run `yarn run start`
+6. In vscode, forward port 3000. This can be found in same pane as the terminal.
+7. Open [http://localhost:3000](http://localhost:3000).
+8. Continue to see [commands](./index.md#running-playnite-web) for running tests.

_docs/contributing/development-environment/index.md

@@ -0,0 +1,38 @@
+# Development Environment
+
+- [Development Environment](#development-environment)
+  - [Overview](#overview)
+  - [Running Playnite Web](#running-playnite-web)
+  - [Playnite Web Plugin Development](#playnite-web-plugin-development)
+
+## Overview
+
+There are a few options for running Playnite Web for local development. Choose and follow one of the paths below. Then proceed to the next section.
+
+1. (preferred) [Local environment](./local-environment.md), directly on your development machine (requires installing required tooling such as Node.js, yarn, etc.).
+2. Via a GitHub codespace (the plugin cannot be run this way).
+3. Via Docker and the included dev container (the plugin cannot be run this way).
+
+> Note the second and third options maybe encounter issues or additional configuration when running component and E2E tests.
+
+## Running Playnite Web
+
+| Application      | Command                           | Notes                                                                                                                                                                                                      |
+| :--------------- | :-------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Playnite Web App | `yarn run start`                  | Run Playnite Web application locally. Navigate to [https://localhost:3000](https://localhost:3000) in a browser. Environment variables are pulled from `./apps/playnite-web/local.env`.                    |
+| Playnite Web App | `yarn run test/components`        | Run component tests for development.                                                                                                                                                                       |
+| Playnite Web App | `yarn run test/components/update` | Run component tests with intention to update a baseline screenshot.                                                                                                                                        |
+| Playnite Web App | `yarn yarn run test/e2e`          | Run end-to-end (e2e) tests for development (including visual regression capabilities). A consistent database restored along with consistent game assets. This ensures a reliable data set to test against. |
+| Playnite Web App | `yarn yarn run test/e2e/update`   | Run end-to-end (e2e) tests with intention to update a baseline screenshot.                                                                                                                                 |
+
+## Playnite Web Plugin Development
+
+To develop the Playnite Web plugin, a Windows machine is required. Playnite must be installed. Recommendation is to use Visual Studio Community edition for development.
+
+1. Install required software
+   - Playnite
+   - Visual Studio
+2. Open the solution file in Visual Studio; located in `apps/PlayniteWebPlugin/src/PlayniteWeb.sln`.
+3. Build the solution.
+4. Open Playnite and add the path to the bin directory as a local plugin. This setting is found under the Developer section in the settings.
+5. Debugging opens Playnite with the plugin installed.

_docs/contributing/development-environment/local-environment.md

@@ -0,0 +1,30 @@
+# Developer Environment: Local
+
+## Required Software
+
+Install the following software on your local development machine:
+
+1. git
+2. Bash (this guide assumes a bash shell)
+3. [vscode](https://code.visualstudio.com/Download)
+4. [Docker](https://www.docker.com/products/docker-desktop/) (for Mongodb and MQTT dependencies)
+5. [Node.js@>=22.5.0](https://nodejs.org/en/download/package-manager) (recommend using `nvm` to manage Node.js installations)
+   - [nvm for OSX](https://github.com/nvm-sh/nvm)
+   - [nvm for Windows](https://github.com/coreybutler/nvm-windows)
+6. [yarn@^4.0.0](https://yarnpkg.com/getting-started)
+   - With Node.js installed, run `corepack enable && corepack prepare --activate yarn@^4.0.0 && yarn set version berry`
+
+## Preparing Codebase
+
+1. [Fork the playnite-web repo](https://github.com/andrew-codes/playnite-web/fork)
+2. Clone your forked repo to your local development machine.
+3. Open the repo in vscode.
+4. Run `yarn`
+5. Run `yarn nx run devenv:prepare`. This is only required for the first time working with the codebase.
+6. Run `yarn run start` and navigate to [https://localhost:3000](https://localhost:3000)
+   - Note that MQTT and Mongo will be started via docker automatically.
+   - Mongo will restore a default database if no database already exists (if there are no files in `.data/mongodb`).
+   - Note MQTT currently starts with no username/password configured.
+7. \[Optional\]: override environment variables when running locally via `cp apps/playnite-web/local.env apps/playnite-web/overrides.env`
+   - **REMEMBER: do not commit `overrides.env` or sensitive information in `local.env`.**
+8. Continue to see [commands](./index.md#running-playnite-web) for running tests.

apps/playnite-web/project.json

@@ -28,7 +28,7 @@
       "executor": "nx:run-commands",
       "options": {
         "cwd": "{projectRoot}",
-        "command": "yarn cross-env NODE_ENV=development yarn node --experimental-json-modules scripts/utils/startDevServer.js"
+        "command": "yarn cross-env NODE_ENV=development DEBUG='playnite*' yarn node --experimental-json-modules scripts/utils/startDevServer.js"
       }
     },
     "test/unit": {

docs/README.md

@@ -10,7 +10,9 @@
 - [api/mqtt](documents/api/mqtt.md)
 - [CONTRIBUTING](documents/CONTRIBUTING.md)
 - [contributing/conventions](documents/contributing/conventions.md)
-- [contributing/development-environment](documents/contributing/development-environment.md)
+- [contributing/development-environment/codespaces](documents/contributing/development-environment/codespaces.md)
+- [contributing/development-environment/index](documents/contributing/development-environment/index.md)
+- [contributing/development-environment/local-environment](documents/contributing/development-environment/local-environment.md)
 - [contributing/rfc](documents/contributing/rfc.md)
 - [design/README](documents/design/README.md)
 - [guides/setup](documents/guides/setup.md)