Skip to Content
🚀 Getting StartedInstallation Setup

Last Updated: 4/7/2026

Installation & Setup

This guide walks you through setting up a local development environment for Agricultural Microworlds using GitHub Codespaces. You’ll go from zero to a running application in about 10 minutes.

Prerequisites

  • A GitHub account with access to the ksu-cs/development-project-agopsimulation repository
  • A web browser

No local installation of Node.js, .NET, or PostgreSQL is required—the devcontainer handles all dependencies.

Step 1: Create a GitHub Codespace

  1. Navigate to the Agricultural Microworlds repository  on GitHub
  2. Click the bright green Code button above the repository file list
  3. Switch to the Codespaces tab
  4. Click the + button to create a new codespace on main

The initial build will take 5-10 minutes as GitHub downloads a Linux universal image, installs the .NET SDK, Node.js, and PostgreSQL 17, and runs npm install in the agricultural-microworlds.client/ directory.

Step 2: Fix Recovery Mode (Expected Issue)

The codespace will most likely open in recovery mode. This happens because GitHub’s free tier storage quota fills up with temporary files. You’ll see a banner at the top of the terminal saying “Running in Recovery Mode.”

To fix this:

  1. Open the terminal (if not already open) with Ctrl + Shift + J (Windows/Linux) or Cmd + Shift + J (Mac)
  2. Run the following command to clear the temporary cache: 
    sudo rm -rf /tmp/*
  3. Press Ctrl + Shift + P (Windows/Linux) or Cmd + Shift + P (Mac) to open the command palette
  4. Type rebuild and select “Codespaces: Rebuild Container”
  5. When prompted, choose Rebuild (not Full Rebuild—Full Rebuild takes much longer)

After the rebuild completes (1-2 minutes), verify the terminal header no longer says “Running in Recovery Mode.”

Step 3: Navigate to the Client Directory

All npm commands must be run from the agricultural-microworlds.client/ directory:

cd agricultural-microworlds.client

Step 4: Install Dependencies

If the postCreateCommand in the devcontainer didn’t complete successfully, manually install npm dependencies:

npm install

This installs React 19, Blockly 12.3.1, Vite 7, and all dev dependencies (ESLint, Prettier, Jest, Babel).

Step 5: Build the Application

Build the Vite frontend bundle:

npm run build

This compiles the React application and outputs static assets to dist/. The build process:

  • Bundles all JavaScript modules
  • Processes CSS
  • Optimizes assets for production
  • Generates source maps

You should see output like:

vite v7.1.7 building for production...
✓ built in 3.45s

Step 6: Start the Development Server

Run the application:

npm run dev

What this does: The dev script changes directory to ../Agricultural-Microworlds.Server and runs dotnet run, which starts the ASP.NET Core backend. The backend serves the Vite-built frontend and proxies API requests.

The terminal will display:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:5000
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5000

A browser tab should automatically open. If not, click the link in the terminal or navigate to the forwarded port in the Ports panel (usually https://<codespace-name>-5000.app.github.dev).

Alternative: Static Vite Server

To run only the Vite dev server (without the ASP.NET backend):

npm run "dev --static"

This is useful for frontend-only development when you don’t need backend API routes. The Vite server runs on port 5000 (configured via DEV_SERVER_PORT environment variable, defaulting to 5000) with hot module replacement (HMR) enabled.

Step 7: Verify the Application

You should see the Agricultural Microworlds interface:

  • Left panel: Blockly workspace with a toolbox of programming blocks (Movement, Farm Operations, Time & Flow, Sensors/Logic)
  • Right panel: Simulation canvas showing a top-down view of a tractor on a field
  • Controls: Run, Stop, and Reset buttons

Test the simulation:

  1. Drag a move_forward block from the toolbox into the workspace
  2. Click the Run button
  3. Watch the tractor move forward one tile in the simulation canvas

If you see the tractor move, congratulations—your development environment is working!

Available npm Scripts

The package.json defines these scripts:

ScriptCommandPurpose
devcd ../Agricultural-Microworlds.Server && dotnet runStart ASP.NET backend (serves frontend)
dev --staticviteStart Vite dev server only (frontend HMR)
dev:svgOPEN_SVG=true viteStart Vite with SVG debugging enabled
buildvite buildBuild production bundle to dist/
testjestRun Jest unit tests
linteslint .Lint JavaScript files with ESLint
previewvite previewPreview production build locally
formatprettier --write .Format code with Prettier

Devcontainer Services

The docker-compose.yml provisions two services:

  1. app: Linux universal image with .NET SDK, Node.js, and development tools
  2. db: PostgreSQL 17 Alpine (accessible on port 5432)

The database is currently unused—authentication and data persistence are not yet implemented.

Troubleshooting

”Cannot find module” errors

Run npm install again. The postCreateCommand may have failed during initial setup.

Port forwarding issues

Check the Ports panel in VS Code. Ensure ports 5000, 5001, and 5432 are forwarded and set to HTTPS protocol.

Codespace keeps entering recovery mode

This is a known issue with GitHub’s storage limits. Run sudo rm -rf /tmp/* and rebuild the container each time you open the codespace.

Vite build fails

Ensure you’re in the agricultural-microworlds.client/ directory. The build command must run from the client folder, not the repository root.

ASP.NET backend won’t start

Check that the .NET SDK is installed: dotnet --version. The devcontainer should provision .NET 9.0 or later.

What’s Next

Now that you have a running development environment:

OverviewSimulation Engine Architecture