Merge pull request #4 from TheLeggett/feature/docker

Add Docker support with configurable SD card mounting

Author: TheLeggett

.dockerignore

@@ -0,0 +1,40 @@
+# Dependencies
+node_modules/
+
+# Build output (rebuilt in container)
+dist/
+
+# Local data and config
+.local/
+.env
+.env.local
+*.log
+
+# Git
+.git/
+.gitignore
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Test files
+*.test.ts
+*.spec.ts
+__tests__/
+coverage/
+
+# Docker files (avoid recursive)
+Dockerfile
+docker-compose*.yml
+.dockerignore
+
+# Documentation (not needed at runtime)
+*.md
+LICENSE

.env.example

@@ -1,3 +1,9 @@
+# Path to your Analogue 3D SD card
+# Default: /Volumes/ANALOGUE 3D (standard macOS mount point)
+# Linux: /media/$USER/ANALOGUE 3D or /run/media/$USER/ANALOGUE 3D
+# Custom SD card name: /Volumes/YOUR_SD_CARD_NAME
+SD_VOLUMES_PATH=/Volumes/ANALOGUE 3D
+
 # Read label artwork directly from SD card instead of local labels.db
 # This is very slow, but keeping here for test purposes.
 # Useful for testing SD card read performance during browsing.

Dockerfile

@@ -0,0 +1,72 @@
+# Build stage
+FROM node:20-slim AS builder
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install all dependencies (including devDependencies for build)
+RUN npm ci
+
+# Copy source files
+COPY . .
+
+# Build the application
+RUN npm run build
+
+# Production stage
+FROM node:20-slim AS production
+
+WORKDIR /app
+
+# Install dumb-init for proper signal handling
+RUN apt-get update && apt-get install -y --no-install-recommends dumb-init && rm -rf /var/lib/apt/lists/*
+
+# Create non-root user for security
+RUN groupadd --gid 1001 nodejs && \
+    useradd --uid 1001 --gid nodejs --shell /bin/bash --create-home nodejs
+
+# Copy package files
+COPY package*.json ./
+
+# Install production dependencies only
+# Sharp requires additional setup for prebuilt binaries
+RUN npm ci --omit=dev
+
+# Copy built frontend from builder stage
+COPY --chown=nodejs:nodejs --from=builder /app/dist ./dist
+
+# Copy server source (tsx runs TypeScript directly)
+COPY --chown=nodejs:nodejs --from=builder /app/server ./server
+
+# Copy tsconfig files for tsx
+COPY --chown=nodejs:nodejs --from=builder /app/tsconfig.json ./
+COPY --chown=nodejs:nodejs --from=builder /app/tsconfig.server.json ./
+
+# Copy data files (cart name database)
+COPY --chown=nodejs:nodejs --from=builder /app/data ./data
+
+# Create local data directory with correct permissions
+RUN mkdir -p .local/Library/N64/Games .local/Library/N64/Images && \
+    chown -R nodejs:nodejs .local
+
+# Switch to non-root user
+USER nodejs
+
+# Expose port
+EXPOSE 3001
+
+# Environment variables
+ENV NODE_ENV=production
+ENV PORT=3001
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD node -e "fetch('http://localhost:3001/api/health').then(r => r.ok ? process.exit(0) : process.exit(1)).catch(() => process.exit(1))"
+
+# Use dumb-init to handle signals properly
+ENTRYPOINT ["dumb-init", "--"]
+
+# Start the server
+CMD ["npm", "start"]

README.md

@@ -134,7 +134,9 @@ Comprehensive N64 cartridge database:
 - Node.js 18 or higher
 - An Analogue 3D with an SD card
 
-### Installation
+### Installation (Recommended)
+
+Native installation is recommended for the best experience, especially if you frequently plug/unplug your SD card.
 
 ```bash
 # Clone the repository
@@ -148,7 +150,93 @@ npm install
 npm run dev
 ```
 
-The app will open at `http://localhost:5173` with the backend API running on port 3001.
+The app will open at `http://localhost:5173` with the backend API running on port 3001. Your SD card will be detected automatically and you can eject/re-insert it freely while the app runs.
+
+### Docker Installation
+
+A3D Manager can also run in Docker, though with some limitations around SD card handling:
+
+```bash
+# Using Docker Compose (recommended)
+docker compose up -d
+
+# Or build and run manually
+docker build -t a3d-manager .
+docker run -d \
+  --name a3d-manager \
+  -p 3001:3001 \
+  -v a3d-data:/app/.local \
+  a3d-manager
+```
+
+The app will be available at `http://localhost:3001`.
+
+#### SD Card Access
+
+The Docker container mounts your Analogue 3D SD card directly. By default, it expects the standard mount path `/Volumes/ANALOGUE 3D`.
+
+> **Important:** Your SD card must be connected and mounted **before** running `docker compose up -d`. If the SD card isn't mounted, Docker will fail with a "permission denied" error.
+
+**Connecting your SD Card:**
+
+You can either use an external SD card reader, or connect directly to your Analogue 3D via USB-C:
+
+1. Fully power off your Analogue 3D and disconnect all controllers and cables
+2. Leave the SD card inserted in the Analogue 3D
+3. Connect the Analogue 3D's power port to your computer using USB-C and wait 5 seconds
+4. Press and hold the reset button, then while holding reset, press and hold the power switch
+5. Hold both buttons until the Power LED turns green, then release
+6. Your SD card should now appear as `ANALOGUE 3D` on your computer
+
+See [Analogue's guide](https://www.analogue.co/support/3d/guide/getting-started#updating-3dos) for more details.
+
+**Initial Setup (macOS):**
+
+1. Connect your SD card (see above)
+2. Run `docker compose up -d`
+
+**Initial Setup (Linux):**
+
+1. Create a `.env` file with your SD card path:
+   ```bash
+   cp .env.example .env
+   # Edit SD_VOLUMES_PATH, e.g.:
+   SD_VOLUMES_PATH=/media/$USER/ANALOGUE 3D
+   ```
+2. Run `docker compose up -d`
+
+**If your SD card has a different name**, create a `.env` file:
+```bash
+SD_VOLUMES_PATH=/Volumes/YOUR_SD_CARD_NAME
+```
+
+#### Ejecting the SD Card (Important)
+
+Due to how Docker Desktop works on macOS, you must **quit Docker Desktop entirely** before ejecting your SD card. The Docker VM keeps file shares active even when containers are stopped.
+
+**Workflow for ejecting:**
+
+1. Stop the container: `docker compose down`
+2. Quit Docker Desktop (click Docker icon in menu bar → Quit Docker Desktop)
+3. Eject your SD card normally
+
+**When ready to use again:**
+
+1. Connect your SD card first (it must be mounted before starting Docker)
+2. Start Docker Desktop
+3. Run `docker compose up -d`
+
+> **Note:** If you frequently need to eject your SD card, consider using the [native installation](#installation-recommended) instead, which has no restrictions on SD card ejection.
+
+#### Docker Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `3001` | Server port |
+| `SD_VOLUMES_PATH` | `/Volumes/ANALOGUE 3D` | Path to your Analogue 3D SD card |
+| `TRANSFER_CHUNK_SIZE` | `2097152` | File transfer chunk size (bytes) |
+| `TRANSFER_FSYNC_PER_CHUNK` | `true` | Sync after each chunk for accurate progress |
+| `READ_LABELS_FROM_SD` | `false` | Read labels directly from SD card (slower) |
 
 ### Quick Start
 

docker-compose.yml

@@ -0,0 +1,36 @@
+services:
+  a3d-manager:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: a3d-manager:latest
+    container_name: a3d-manager
+    ports:
+      - "3001:3001"
+    volumes:
+      # Persist local library data (cartridge art, games metadata)
+      - a3d-data:/app/.local
+      # Mount SD card for detection and sync
+      # Configure via SD_VOLUMES_PATH in .env file
+      # Default: /Volumes/ANALOGUE 3D (standard Analogue 3D SD card name)
+      - "${SD_VOLUMES_PATH:-/Volumes/ANALOGUE 3D}:${SD_VOLUMES_PATH:-/Volumes/ANALOGUE 3D}:rw"
+    environment:
+      - NODE_ENV=production
+      - PORT=3001
+      - SD_VOLUMES_PATH=${SD_VOLUMES_PATH:-/Volumes/ANALOGUE 3D}
+      # File transfer settings
+      - TRANSFER_CHUNK_SIZE=2097152
+      - TRANSFER_FSYNC_PER_CHUNK=true
+      # Set to 'true' to read labels directly from SD card (slower)
+      - READ_LABELS_FROM_SD=false
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://localhost:3001/api/health').then(r => r.ok ? process.exit(0) : process.exit(1)).catch(() => process.exit(1))"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 5s
+
+volumes:
+  a3d-data:
+    name: a3d-manager-data

docs/TESTING.md

@@ -31,6 +31,8 @@ tests/
 ├── cartridge-data/
 │   ├── tests.ts            # Cartridge data tests
 │   └── output/             # Generated output (gitignored)
+├── sd-card/
+│   └── tests.ts            # SD card configuration tests
 └── game-data/
     └── fixtures/           # Shared fixtures (settings.json, controller_pak.img)
 
@@ -122,6 +124,16 @@ Tests for cartridge ownership tracking, settings parsing, and game pak operation
 
 ---
 
+## SD Card Configuration Tests (4 tests)
+
+Tests for SD card detection and Docker volume path configuration.
+
+| Category | Tests | Description |
+|----------|-------|-------------|
+| Volumes Path | 4 | SD_VOLUMES_PATH env var, default /Volumes, Linux/macOS paths |
+
+---
+
 ## Interactive Benchmarks (Settings Page)
 
 The Settings page (`/settings`) includes interactive benchmarks for testing SD card performance with a connected SD card.

package.json

@@ -11,6 +11,7 @@
     "dev:client": "vite",
     "dev:server": "tsx watch server/index.ts",
     "build": "tsc -b && vite build",
+    "start": "NODE_ENV=production node --import tsx server/index.ts",
     "lint": "eslint .",
     "preview": "vite preview"
   },
@@ -25,7 +26,8 @@
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "react-router-dom": "^7.11.0",
-    "sharp": "^0.33.5"
+    "sharp": "^0.33.5",
+    "tsx": "^4.19.4"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.1",
@@ -43,7 +45,6 @@
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.4.24",
     "globals": "^16.5.0",
-    "tsx": "^4.19.4",
     "typescript": "~5.9.3",
     "typescript-eslint": "^8.46.4",
     "vite": "^7.2.4"

server/index.ts

@@ -36,6 +36,17 @@ app.get('/api/health', (_req, res) => {
   res.json({ status: 'ok', timestamp: new Date().toISOString() });
 });
 
+// Serve static files in production
+if (process.env.NODE_ENV === 'production') {
+  const distPath = path.join(process.cwd(), 'dist');
+  app.use(express.static(distPath));
+
+  // SPA fallback - serve index.html for all non-API routes
+  app.get('*', (_req, res) => {
+    res.sendFile(path.join(distPath, 'index.html'));
+  });
+}
+
 // Start server
 async function start() {
   await ensureLocalDirs();