{"id":15407074,"url":"https://github.com/ltfschoen/mudtemplate","last_synced_at":"2025-08-03T18:31:46.951Z","repository":{"id":166318102,"uuid":"641801770","full_name":"ltfschoen/MUDTemplate","owner":"ltfschoen","description":"Build Ethereum DApps with MUD v2 in a Docker container","archived":false,"fork":false,"pushed_at":"2023-08-16T12:01:20.000Z","size":158,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-19T16:00:11.665Z","etag":null,"topics":["anvil","cast","chisel","docker","ethereum","ethglobal23","forge","foundry","lattice","mud","vitejs"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ltfschoen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-17T07:41:27.000Z","updated_at":"2024-10-16T14:40:33.000Z","dependencies_parsed_at":"2024-10-19T12:35:39.037Z","dependency_job_id":"4fa0072e-8f66-48ba-90d4-f3ffef57505f","html_url":"https://github.com/ltfschoen/MUDTemplate","commit_stats":{"total_commits":27,"total_committers":2,"mean_commits":13.5,"dds":0.07407407407407407,"last_synced_commit":"a93cfcb231c0698f68ae00979f51217b87626b13"},"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ltfschoen%2FMUDTemplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ltfschoen%2FMUDTemplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ltfschoen%2FMUDTemplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ltfschoen%2FMUDTemplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ltfschoen","download_url":"https://codeload.github.com/ltfschoen/MUDTemplate/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228557179,"owners_count":17936452,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anvil","cast","chisel","docker","ethereum","ethglobal23","forge","foundry","lattice","mud","vitejs"],"created_at":"2024-10-01T16:26:58.648Z","updated_at":"2024-12-07T04:05:25.842Z","avatar_url":"https://github.com/ltfschoen.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MUD v2 DApp Template (using Docker)\n============\n\n## Table of Contents\n\n  * [Create New MUD v2 Project](#create-new-project)\n  * [Tips to configure Visual Studio Code](#vscode)\n  * [Tips for Docker](#docker-tips)\n  * [Tips for Lattice, UD, and Foundry](#misc-notes)\n  * [Tips when Troubleshooting](#troubleshooting)\n  * [Tips with Links](#links-unsorted)\n\n### Create First Project \u003ca id=\"create-new-project\"\u003e\u003c/a\u003e\n\n* Install [Docker](https://docs.docker.com/get-docker/)\n* Fork and/or clone repo.\n  ```bash\n  git clone https://github.com/ltfschoen/MUDTemplate \u0026\u0026 cd MUDTemplate\n  ```\n* Configure DApp by generating a .env file from the .env.example file by following its instructions, if desired.\n* Build a Docker image and run a Docker container to create a DApp according to configuration in .env file.\n  ```bash\n  ./docker/docker.sh\n  ```\n* Wait... until terminal logs output `[client] Local: http://localhost:3000/`\n* Open http://localhost:3000 in web browser to load MUD v2 DApp.\n\n#### Restart Existing Project\n\n* Enter the Docker container shell with the following. It should display a prompt `root@foundry:/opt#`.\n  ```bash\n  docker exec -it foundry /bin/bash\n  ```\n* To manually start the MUD v2 DApp switch to the folder of your MUD v2 DApp and run it with:\n  ```bash\n  cd /opt/projects/my-project\n  pnpm run dev\n  ```\n* Press CTRL+D to exit Docker container shell.\n\n#### Create Additional Projects\n\n* Option 1\n  * Run\n    ```bash\n    docker exec -it foundry ./docker/run.sh \u003cPROJECT_NAME\u003e \u003cTEMPLATE\u003e \u003cLICENSE\u003e\n    ```\n* Option 2\n  * Enter the Docker container shell with the following. It should display a prompt `root@foundry:/opt#`.\n    ```bash\n    docker exec -it foundry /bin/bash\n    ```\n  * Create a MUD v2 DApp by running:\n    ```bash\n    /opt/docker/run.sh \u003cPROJECT_NAME\u003e \u003cTEMPLATE\u003e \u003cLICENSE\u003e\n    ```\n  * Press CTRL+D to exit Docker container shell.\n\u003e Note: See .env.example for possible values to use for `\u003cPROJECT_NAME\u003e`, `\u003cTEMPLATE\u003e`, and `\u003cLICENSE\u003e`.\n\n### Tips to configure Visual Studio Code \u003ca id=\"vscode\"\u003e\u003c/a\u003e\n\n* Edit my-project/.vscode/settings.json if necessary. Note in ./docker/run.sh we replace its contents with default values in the file ./snippets/content-settings.json\n\n* Verify that the Solidity version value specified in the following files for the following keys is the same (i.e. `0.8.x`). See https://github.com/foundry-rs/foundry/blob/58a272997516046fd745f4b3c37f91d0eb113358/config/src/lib.rs#L179\n    * `solc_version` or `solc` ./projects/my-project/packages/contracts/foundry.toml\n    * `solidity.compileUsingRemoteVersion` in ./.vscode/settings.json.\n    * `solidity.compileUsingRemoteVersion` in ./projects/my-project/.vscode/settings.json.\n\n### Tips for Docker \u003ca id=\"docker-tips\"\u003e\u003c/a\u003e\n\n* Delete Docker Container \n  ```\n  docker stop foundry \u0026\u0026 docker rm foundry\n  ```\n* Show Docker Containers\n  ```bash\n  docker ps -a\n  ```\n* Show Docker Images\n  ```bash\n  docker images\n  ```\n* Previous Docker container\n  ```bash\n  CONTAINER_ID=$(docker ps -n=1 -q)\n  echo $CONTAINER_ID\n  ```\n* Show IP address. This may be provided as an environment variable with `-e` option\n  ```bash\n  HOST_IP=$(ip route get 1 | sed -n 's/^.*src \\([0-9.]*\\) .*$/\\1/p')\n  echo $HOST_IP\n  ```\n* [Check IP Address macOS](https://stackoverflow.com/questions/24319662/from-inside-of-a-docker-container-how-do-i-connect-to-the-localhost-of-the-mach)\n  ```bash\n  brew install iproute2mac\n  ```\n* Show bridge IP address\n  ```bash\n  docker network inspect bridge | grep Gateway\n  ```\n\n\u003e Note: It is not necessary to use `--add-host=host.docker.internal:host-gateway` or `expose \u003cPORT\u003e`\n\n\u003e Note: Do not try to use `--network host` on macOS, since _\"The host networking driver only works on Linux hosts, and is not supported on Docker Desktop for Mac, Docker Desktop for Windows, or Docker EE for Windows Server.\"_\n\n### Tips for Lattice, MUD, and Foundry\u003ca id=\"misc-notes\"\u003e\u003c/a\u003e\n\n#### Definitions\n\n* MODE - is a service that mirrors the state of a Store in a Postgres database. Clients query directly without requiring Ethereum JSON-RPC\n* MUD - able to reconstruct the state of Store in the browser using a JSON-RPC or a MODE\n\n#### Faucet\n\n* Faucet tokens request\n  * Check the available flags via `--help` like `npx @latticexyz/cli@canary faucet --help`\n  * Request Testnet tokens from faucet (FAST way)\n    * Run in a project that has the MUD CLI installed as a dev dependency, or via npx like `npx @latticexyz/cli@canary faucet --address \u003cADDRESS\u003e`. \n  * Request Testnet Tokens from Faucet (SLOW way)\n    * Install Foundry `curl -L https://foundry.paradigm.xyz | bash`\n    * Install Go\n    * Install MUD and request testnet token from faucet\n      ```bash\n      npm install pnpm --global \u0026\u0026 \\\n      git clone https://github.com/latticexyz/mud \u0026\u0026 \\\n      cd mud \u0026\u0026 \\\n      pnpm install \u0026\u0026 \\\n      pnpm run build \u0026\u0026 \\\n      cd packages/cli \u0026\u0026 \\\n      pnpm install \u0026\u0026 \\\n      pnpm run build \u0026\u0026 \\\n      node ./dist/mud.js faucet --faucetUrl \"https://follower.testnet-chain.linfra.xyz\" --address \u003cADDRESS\u003e\n      ```\n\n#### Q\u0026A\n\n* Where is MUD v2 code stored?\n  * All the MUD v2 is in the main branch of https://github.com/latticexyz/mud. The tags do not show up since it is released as canary for now, but you can see the versions on https://www.npmjs.com/package/@latticexyz/world?activeTab=versions. To use MUD v2 you would run `pnpm create mud@canary my-project`, since PNPM is preferable over `Yarn`. If store-cache hasn't been published, run `pnpm create mud@2.0.0-alpha.1.93 my-project`:\n\n* Where is the MUD v2 DApp template stored for React?\n  * If you choose to use the React template, then changes to the upstream template code occurs here https://github.com/latticexyz/mud/commits/main/templates/react\n\n* How to install additional global MUD v2 dependencies if necessary \n  * Additional dependencies may be required such as: `pnpm install --global concurrently wait-port`\n\n* How to edit the Store config?\n  * Use mud.config.ts to edit your Store config directly https://v2.mud.dev/store/installation\n\n* How to update the client/ and contracts/ folder of the MUD v2 DApp to the latest canary version?\n  * Run `pnpm mud set-version -v canary` in both the client and contracts package of your project then run `pnpm install` at the root to update your project to the latest canary version\n\n### Tips when Troubleshooting \u003ca id=\"troubleshooting\"\u003e\u003c/a\u003e\n\n**Please create an issue by clicking [here](https://github.com/ltfschoen/MUDTemplate/issues) and describing the error and upload a screenshot of any errors.**\n\n* How to resolve PNPM global bin directory error\n  * If you get the following error when running `pnpm run dev`, then it may be because you previously built the files on a host machine and copied them to a Docker container.\n    ```bash\n    sh: 1: run-pty: not found\n     ELIFECYCLE  Command failed.\n    root@docker-desktop:/opt/projects/my-first-mud-project# pnpm install --global run-pty\n     ERR_PNPM_NO_GLOBAL_BIN_DIR  Unable to find the global bin directory\n    Run \"pnpm setup\" to create it automatically, or set the global-bin-dir setting, or the PNPM_HOME env variable. The global bin directory should be in the PATH.\n    ```\n  * Solution is to run `pnpm setup`, which added this to ~/.bashrc:\n    ```\n    # pnpm\n    export PNPM_HOME=\"/root/.local/share/pnpm\"\n    case \":$PATH:\" in\n      *\":$PNPM_HOME:\"*) ;;\n      *) export PATH=\"$PNPM_HOME:$PATH\" ;;\n    esac\n    ```\n  * Then run the following where `~/.local/share/pnpm` is `$PNPM_HOME`\n    ```bash\n    source ~/.bashrc\n    pnpm config set global-bin-dir ~/.local/share/pnpm\n    ```\n\n* How to resolve PNPM dashboard errors\n  * Note: If after running DApp with `pnpm run dev`, if you click 1-pnpm dev:client then it should show that it is exposed at http://localhost:3000 and maybe http://172.17.0.2:3000, where 172.17.0.2 is the eth0 IP address shown if you run `ifconfig`\n  * If any errors running `pnpm run dev` in the dashboard, then press CTRL+C and then Enter to restart the dashboard and the error should disappear\n\n* How to resolve CORS error `Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at http://127.0.0.1:8545/. (Reason: CORS request did not succeed). Status code: (null)`\n  * Refer to solution here of running with `export ANVIL_IP_ADDR=0.0.0.0 \u0026\u0026 pnpm run dev` https://github.com/vitejs/vite/discussions/13240#discussioncomment-5934467\n  * Note that in the latest MUD v2 updates where they use `concurrently` instead of `run-pty` you would get CORS errors but we use `wait-port` so it only loads the DApp when port 8545 is ready.\n\n* How to configure CORS\n  * The CORS configuration may include adding `\"proxy\": \"http://\u003cHOST\u003e:\u003cPORT\u003e\",` in a package.json file and updating \u003cyour-project\u003e/packages/client/vite.config.ts with a `cors` configuration with keys and values like the below example and replacing \u003cPORT\u003e with an actual port. The below example is not intended to actually work. Refer to Vite.js configuration documentation for more information https://vitejs.dev/config/server-options.html#server-cors, and also https://github.com/http-party/node-http-proxy#options\n  * If you change the CORS configuration for the Vite.js DApp frontend by configuring ./projects/my-project/packages/client/vite.config.ts. See https://vitejs.dev/config/server-options.html#server-cors, then run `pnpm store prune` and restart the DApp.\n  * Note that you may open all origins with: `cors: { origin: \"*\", methods: ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE', 'OPTIONS'] },`.\n    \u003cdetails\u003e\u003csummary\u003eExample CORS code snippet\u003c/summary\u003e\n\n      ```json\n      cors: {\n        // origin: [\"ws://127.0.0.1:\u003cPORT\u003e/\", \"http://127.0.0.1:\u003cPORT\u003e/\"],\n        origin: \"*\",\n        methods: ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE', 'OPTIONS'],\n        allowedHeaders: ['Content-Type', 'Authorization'],\n        credentials: true,\n        exposedHeaders: ['Content-Range', 'X-Content-Range'],\n        preflightContinue: true,\n        optionsSuccessStatus: 204\n      },\n      hmr: {\n        clientPort: \u003cPORT\u003e,\n        port: \u003cPORT\u003e,\n        overlay: false,\n      },\n      proxy: {\n        '/socket.io': {\n          target: 'ws://localhost:\u003cPORT\u003e',\n          changeOrigin: true,\n          ws: true,\n          xfwd: true,\n        },\n      },\n      strictPort: false,\n      ```\n\n    \u003c/details\u003e\n\n* How to resolve a port being in use?\n  * If port 3000 is in use, then find its PID `lsof -i | grep :3000` and then kill it by running `kill -9 \u003cPID\u003e`\n\n### Tips with Links\u003ca id=\"links-unsorted\"\u003e\u003c/a\u003e\n\n* MUD v1 (legacy)\n  * https://mud.dev/guides/getting_started/\n* MUD v2\n  * Codebase\n    * https://github.com/latticexyz/mud\n  * Documentation\n    * https://v2.mud.dev/what-is-mud\n    * https://v2.mud.dev/mode\n    * https://v2.mud.dev/store\n  * Dependencies\n    * Lattice\n      * https://www.npmjs.com/package/@latticexyz\n* Foundry (Forge, Cast, Anvil, Chisel)\n  * Codebase\n    * https://github.com/foundry-rs/foundry\n  * Documentation\n    * https://getfoundry.sh/\n    * https://book.getfoundry.sh/\n    * https://book.getfoundry.sh/getting-started/installation\n* Anvil\n  * https://book.getfoundry.sh/anvil/\n  * https://book.getfoundry.sh/reference/anvil/\n* Example Projects\n  * https://github.com/latticexyz/emojimon\n  * https://github.com/latticexyz/opcraft\n  * List of MUD games https://community.mud.dev/MUD-Projects-2996171a4b4b472b9df557f8bfdd3c49\n  * MUD unity game https://github.com/emergenceland/mud-template-unity\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fltfschoen%2Fmudtemplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fltfschoen%2Fmudtemplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fltfschoen%2Fmudtemplate/lists"}