Skip to main content

​
Overview

SushiGo is a monorepo project with a Laravel API and React webapp. Development is done inside a Docker container using VS Code’s devcontainer feature for a consistent, isolated environment.

​
Prerequisites

Before you begin, ensure you have installed:
  • Docker Desktop (latest version)
  • VS Code with the “Dev Containers” extension (ms-vscode-remote.remote-containers)
  • Git for version control

​
Quick Start

1

Clone the repository

git clone <repository-url> sushigo
cd sushigo
2

Configure hosts file

Add the following entries to your system’s hosts file:Linux/macOS: /etc/hosts
Windows: C:\Windows\System32\drivers\etc\hosts
127.0.0.1  sushigo.local
127.0.0.1  api.sushigo.local
127.0.0.1  devtest.sushigo.local
127.0.0.1  devtest.api.sushigo.local
On Linux/macOS, use: sudo nano /etc/hosts
3

Open in VS Code

code .
VS Code will detect the .devcontainer/devcontainer.json file and prompt you to reopen in container.
4

Reopen in Container

Click “Reopen in Container” when prompted, or use:
  • Press Ctrl+Shift+P (or Cmd+Shift+P on macOS)
  • Select “Dev Containers: Reopen in Container”
The first build will take several minutes to pull images and install dependencies.
5

Wait for container initialization

The container will automatically:
  • Install PHP dependencies via Composer
  • Install Node.js dependencies via npm
  • Run database migrations
  • Seed the database
  • Generate Swagger documentation
6

Verify setup

Once the container is running, open the integrated terminal and verify:
# Check API health
curl http://localhost/api/v1/health

# Check database connection
docker exec -it dev_container bash -c "cd /app/code/api && php artisan migrate:status"

​
Container Structure

The monorepo maps to the following paths inside dev_container:
Sub-projectHost pathContainer path
API (Laravel)code/api//app/code/api
Webapp (React)code/webapp//app/code/webapp
Documentationdoc//app/doc
All php artisan commands must run from /app/code/api inside the container.

​
Access URLs

After setup, you can access:
ServiceURLCredentials
Webapphttps://sushigo.local[email protected] / admin123456
Webapp (direct Vite)http://localhost:5173-
APIhttps://api.sushigo.local/api/v1-
Swagger UIhttp://localhost:8080/api/documentation-
PgAdminhttp://localhost:5050[email protected] / admin
Mailhoghttp://localhost:8025-

​
Default Test Users

RoleEmailPassword
Super Admin[email protected]admin123456
Admin[email protected]admin123456
Inventory Manager[email protected]inventory123456

​
VS Code Extensions

The devcontainer automatically installs these recommended extensions:

​
AI & Productivity

  • GitHub Copilot
  • GitHub Copilot Chat
  • ChatGPT (OpenAI)

​
Laravel / PHP

  • Laravel Extra Intellisense
  • Laravel Goto Controller
  • Laravel Artisan
  • Intelephense (PHP IntelliSense)
  • Laravel Blade

​
React / JavaScript / TypeScript

  • ESLint
  • Prettier
  • ES7+ React/Redux snippets
  • Auto Rename Tag

​
DevOps & Tools

  • Docker
  • Remote Containers
  • GitLens

​
SSL Certificates

The development environment uses self-signed SSL certificates for HTTPS.

​
Installing Root Certificate

# Trust the root CA
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain \
  docker/app/config/dev/cert/rootCA.pem

​
Clearing Chrome HSTS Cache

If you see SSL errors in Chrome, clear the HSTS cache:
1

Open Chrome HSTS settings

Navigate to: chrome://net-internals/#hsts
2

Delete domain security policies

In the “Delete domain security policies” section:
  • Enter: localhost or sushigo.local
  • Click Delete
3

Restart containers

docker compose restart dev
Alternatively, use Chrome’s Incognito mode: Cmd+Shift+N (macOS) or Ctrl+Shift+N (Windows/Linux)

​
Database Setup

​
Creating Test Database

The test database is created automatically, but if you need to recreate it manually: 
docker exec -it dev_container psql -h pgsql -U admin -d mydb -c "CREATE DATABASE mydb_test;"

​
Running Migrations and Seeders

# Inside the container
cd /app/code/api

# Run migrations
php artisan migrate

# Seed database
php artisan db:seed

# Fresh migration with seeding
php artisan migrate:fresh --seed

# Check seeder status
php artisan seeder:status

​
Common Setup Issues

If ports 80, 443, 5432, or 5173 are already in use:
# Find process using port
lsof -i :5432  # macOS/Linux
netstat -ano | findstr :5432  # Windows

# Stop conflicting services
# Then restart containers
docker compose down
docker compose up --build
If you encounter permission errors in the container:
# Fix Laravel storage permissions
docker exec -it dev_container bash -c "cd /app/code/api && chmod -R 777 storage bootstrap/cache"

# Fix node_modules permissions
docker exec -it dev_container bash -c "cd /app/code/webapp && npm install"
Wait for PostgreSQL to be fully ready:
# Check PostgreSQL health
docker exec -it postgres_container pg_isready -U admin -d mydb

# View PostgreSQL logs
docker logs postgres_container
If Hot Module Replacement doesn’t work:
  1. Ensure sushigo.local is in your hosts file
  2. Check VITE_HMR_HOST environment variable in docker-compose.yml
  3. Restart the dev container: 
    docker compose restart dev

​
Next Steps

Docker Compose

Learn about the Docker services architecture

Testing

Run backend, frontend, and E2E tests

Conventions

Follow project code and Git conventions

Build docs developers (and LLMs) love

Get started for freeTalk to us