Skip to content

Complete_Setup_Instructions.md

Latest commit

 

History

History
284 lines (203 loc) · 7.22 KB

Complete_Setup_Instructions.md

File metadata and controls

284 lines (203 loc) · 7.22 KB

Complete Setup Instructions for jsavage/depict

Current Status

Your repository at https://github.com/jsavage/depict has the core scripts committed. Now let's add the remaining files and get everything working.

Files You Should Add

1. GitHub Actions Workflow (Essential for CI/CD)

File: .github/workflows/build-and-test.yml

This file enables automatic builds and tests on every push. I created this in artifact github-workflow.

Why you need it:

  • Automatically runs diagnostics on every commit
  • Tests all build methods (Cargo, Nix, Docker)
  • Runs integration tests
  • Saves build artifacts for 30 days
  • You can download diagnostics without running locally

2. Dockerfile (Optional but Recommended)

File: Dockerfile

I created this in artifact dockerfile-ubuntu. It provides Ubuntu 22.04 build environment.

Why you need it:

  • Avoids Ubuntu 24.04 issues
  • Reproducible builds
  • Clean environment
  • Useful for local testing without contaminating your system

3. Documentation Files (Highly Recommended)

Files:

  • BUILD_SYSTEM.md - Complete documentation
  • QUICK_START.txt - Generated by setup script

These explain how to use the build system.

Step-by-Step Setup

On Your Development Server

# 1. Clone your fork (if not already done)
git clone https://github.com/jsavage/depict.git
cd depict

# 2. Make scripts executable
chmod +x diagnose.sh build.sh test.sh setup_build_system.sh

# 3. Run setup (interactive)
./setup_build_system.sh

This will:

  • Check if Rust is installed
  • Offer to install trunk and wasm-bindgen-cli
  • Run initial diagnostics
  • Optionally start a build

To Add Missing Files to GitHub

# Create the workflows directory
mkdir -p .github/workflows

# Add the workflow file (copy from artifact 'github-workflow')
# Save it as .github/workflows/build-and-test.yml

# Add Dockerfile (copy from artifact 'dockerfile-ubuntu')
# Save it as Dockerfile

# Add documentation (copy from artifacts)
# Save as BUILD_SYSTEM.md

# Commit and push
git add .github/workflows/build-and-test.yml
git add Dockerfile
git add BUILD_SYSTEM.md
git commit -m "Add CI/CD workflow, Dockerfile, and documentation"
git push origin main

What Happens After Push

Once you push the workflow file, GitHub Actions will automatically:

  1. On every push to main:

    • Run diagnostics job
    • Attempt builds with Cargo, Nix, and Docker
    • Run integration tests (if build succeeds)
    • Upload all results as artifacts

  2. View results:

  3. Artifacts available:

    • diagnostics-<SHA> - Complete project state
    • build-cargo-<SHA> - Cargo build results
    • build-nix-<SHA> - Nix build results (may fail)
    • build-docker-<SHA> - Docker build results
    • test-results-<SHA> - Test output and exported SVGs

Usage Scenarios

Scenario 1: First Time Setup (Local)

# On your development server
cd depict
./setup_build_system.sh

# Answer prompts:
# - Install trunk? y
# - Install wasm-bindgen-cli? y
# - Run initial build? y
# - Run tests? y

Scenario 2: Regular Development (Local)

# After making code changes
./diagnose.sh          # Check current state
./build.sh --clean     # Clean build
./test.sh              # Verify it works

Scenario 3: Using GitHub Actions (Automatic)

# Just push your changes
git add .
git commit -m "Update feature X"
git push

# Then visit GitHub Actions to see results
# Download artifacts if build fails

Scenario 4: Docker Build (Local)

# Build Docker image
docker build -t depict-builder .

# Run interactive shell
docker run -it --rm -v $(pwd):/workspace depict-builder

# Inside container:
./diagnose.sh
./build.sh
./test.sh --port 8080

Scenario 5: Sharing Results with Claude

After running diagnostics locally:

# Find latest diagnostic archive
ls -t diagnostics/*.tar.gz | head -1

# Upload this file to Claude in your next conversation
# Or upload specific .txt files from diagnostics/YYYYMMDD_HHMMSS/

Script Execution Matrix

Script Local Dev Server GitHub Actions Docker Container
setup_build_system.sh ✅ Run once ❌ Don't use ✅ Can use
diagnose.sh ✅ Run anytime ✅ Automatic ✅ Run anytime
build.sh ✅ Run anytime ✅ Automatic ✅ Run anytime
test.sh ✅ Run anytime ✅ Automatic ✅ Run anytime

Current Files in Your Repo

Based on the visible structure, you have:

  • ✅ diagnose.sh
  • ✅ build.sh
  • ✅ test.sh
  • ✅ setup_build_system.sh

Still need:

  • ⚠️ .github/workflows/build-and-test.yml (for CI/CD)
  • ⚠️ Dockerfile (for reproducible builds)
  • ⚠️ BUILD_SYSTEM.md (documentation)

Quick Test of Current Setup

To verify your current scripts work:

# On your development server
cd ~/depict  # or wherever you cloned it

# Make executable (if not already)
chmod +x *.sh

# Quick test
./diagnose.sh

# Check output
LATEST=$(ls -t diagnostics/ | grep '^[0-9]' | head -1)
cat "diagnostics/$LATEST/00_SUMMARY.txt"

This will show:

  • Your Rust version
  • WASM target status
  • Workspace packages
  • Current git state

Next Steps

  1. Immediate: Run ./setup_build_system.sh on your development server to check current state

  2. Within 24 hours: Add the GitHub Actions workflow file so you get automatic builds on every push

  3. Optional: Add Dockerfile for reproducible Ubuntu 22.04 builds

  4. After first run: Share the diagnostics/*.tar.gz file with me so I can see your exact environment and help debug any issues

Getting the Files

Since I created these as artifacts in this conversation:

  1. For .github/workflows/build-and-test.yml:

    • Copy the content from the "github-workflow" artifact above
    • Create the file locally
    • Commit and push

  2. For Dockerfile:

    • Copy from the "dockerfile-ubuntu" artifact above
    • Save as Dockerfile in repo root
    • Commit and push

  3. For BUILD_SYSTEM.md:

    • Copy from the "build-system-readme" artifact above
    • Save as BUILD_SYSTEM.md
    • Commit and push

Troubleshooting

If setup_build_system.sh fails:

# Run components individually
./diagnose.sh                    # Always works
./build.sh --method cargo        # Attempt build
cat build_output/*/logs/*.log    # Check errors

If GitHub Actions fails:

  1. Go to Actions tab in your repo
  2. Click failed workflow
  3. Download diagnostic artifacts
  4. Share with me for analysis

If you're unsure what to do:

Just run this and share the output with me:

./diagnose.sh
tar -czf my-diagnostics.tar.gz diagnostics/$(ls -t diagnostics/ | grep '^[0-9]' | head -1)
# Upload my-diagnostics.tar.gz to Claude

Summary

  • setup_build_system.sh: Run once on your local dev server (interactive)
  • GitHub Actions workflow: Runs automatically on every push (add the .yml file)
  • Manual scripts: Run anytime locally for development
  • Docker: Optional isolated environment for clean builds

The workflow file is the most important missing piece - it will give you automatic diagnostics and build attempts on every commit!