Project Sandbox Development Environment

A containerized development environment system that provides isolated, ephemeral workspaces with persistent file storage.

Quick Start

cd ~/path/to/your/project
project                    # Enter the sandbox
# ... do your work ...
exit                       # Leave sandbox (container deleted, files persist)

How It Works

The project command creates a fresh Docker container with a complete development toolchain, mounts your current directory, and automatically cleans up when you exit - while keeping all your files and project-specific caches.

Components

1. Alias (~/.bashrc:203)

   alias project='docker-compose -f ~/Code/compose.yaml run --rm workbench'

2. Docker Compose (~/Code/compose.yaml)

   • Defines the "workbench" service
   • Mounts current directory as /app
   • Configures environment variables for project isolation

3. Dockerfile (~/Code/Dockerfile.project)

   • Ubuntu 24.04 base image
   • Multi-language development stack
   • Pre-configured ubuntu user (UID 1000)

Architecture

What Gets Mounted

Host: ${PWD}              → Container: /app (your HOME)
Host: /tmp/.X11-unix      → Container: /tmp/.X11-unix (GUI support)

Environment Variables

• HOME=/app - Your project directory becomes home
• HISTFILE=/app/.bash_history - Bash history per project
• CARGO_HOME=/app/.cargo - Rust dependencies isolated per project
• NPM_CONFIG_CACHE=/app/.npm - npm cache isolated per project
• DISPLAY=$DISPLAY - GUI application support

User Mapping

• Runs as UID:GID 1000:1000 (matches host user)
• No permission issues between host and container
• Files created in container are owned by you on the host

Installed Tools

Languages & Runtimes

• Python 3 - with pip and venv
• Node.js - with npm
• Java 17 - OpenJDK
• .NET 8.0 - SDK
• Rust - via rustup (stable toolchain)

Build Tools & Libraries

• build-essential (gcc, g++, make)
• cmake
• pkg-config
• libssl-dev

Utilities

• git
• curl
• sudo (passwordless for ubuntu user)

GPU Support

• Full NVIDIA GPU access via runtime
• All GPUs available (capabilities: [gpu])

File Persistence

What Persists (After Exit)

✅ All files in /app (your project directory) ✅ .bash_history (bash command history) ✅ .cargo/ (Rust dependencies) ✅ .npm/ (npm cache) ✅ Any code, configs, or data you create

What Gets Deleted (After Exit)

❌ The container instance ❌ Files outside /app (e.g., /tmp, /home/ubuntu) ❌ System changes (installed packages, config outside /app) ❌ Global modifications (unless saved to /app)

Example Workflow

# On host
cd ~/Code/Coding/some-project
project

# Inside container (prompt: ubuntu@kubuntu:~$)
echo "hello" > test.txt
cargo init --name myapp
npm init -y
python3 -m venv .venv
exit

# Back on host - all files still there
ls
# Output: test.txt  Cargo.toml  src/  package.json  .venv/

Use Cases

1. Quick Experiments

Try out a new library or framework without polluting your system:

mkdir /tmp/experiment
cd /tmp/experiment
project
cargo new hello-rust
cd hello-rust
cargo run
exit
# Clean up when done: rm -rf /tmp/experiment

2. Project Isolation

Each project gets its own dependency tree:

cd ~/Code/project-a
project
npm install react@18.0.0    # Only in project-a

# In another terminal
cd ~/Code/project-b
project
npm install react@17.0.0    # Only in project-b

3. Multi-Language Projects

Work with multiple languages in one environment:

cd ~/Code/fullstack-app
project
# Backend
cargo build --release
# Frontend
npm run build
# Scripts
python3 deploy.py
exit

4. Reproducible Builds

Same environment every time, regardless of host state:

# Teammate A's machine
cd ~/project && project && cargo build

# Teammate B's machine (same Docker image)
cd ~/project && project && cargo build
# Identical build environment

Benefits

Feature	Benefit
Isolation	Each project has its own dependencies
Reproducibility	Consistent environment across machines
Cleanliness	No cruft - containers are ephemeral
Portability	Share compose.yaml with teammates
GPU Access	ML/compute work with full GPU support
Multi-language	All languages available instantly
No Cleanup	Container auto-deleted on exit

Advanced Usage

Installing Additional Packages

project
sudo apt-get update
sudo apt-get install -y tmux htop
# Use tools...
exit
# Note: Packages gone on next run. Add to Dockerfile.project for persistence.

Modifying the Environment

Edit ~/Code/Dockerfile.project to add permanent tools:

RUN apt-get update && apt-get install -y \
    your-package-here \
    && rm -rf /var/lib/apt/lists/*

Then rebuild:

cd ~/Code
docker-compose build workbench

Running GUI Applications

GUI apps work automatically (X11 socket is mounted):

project
# GUI apps will display on your host

Troubleshooting

"Cannot connect to Docker daemon"

sudo systemctl start docker
sudo usermod -aG docker $USER
# Log out and back in

"Permission denied" errors

Check that you're UID 1000:

id -u  # Should output: 1000

Container fails to start

Rebuild the image:

cd ~/Code
docker-compose build --no-cache workbench

Need to clear project caches

cd ~/Code/your-project
rm -rf .cargo .npm node_modules target/
project  # Fresh dependency install

File Structure

~/Code/
├── compose.yaml              # Docker Compose configuration
├── Dockerfile.project        # Container image definition
└── PROJECT-SANDBOX-README.md # This file

~/.bashrc
└── alias project='...'       # Line 203

Your Project/
├── .bash_history             # Your command history
├── .cargo/                   # Rust dependencies (if used)
├── .npm/                     # npm cache (if used)
├── .venv/                    # Python venv (if created)
└── [your files]              # All your project files

Tips

• History search: Your bash history persists per-project in .bash_history
• Clean slate: Delete .cargo/, .npm/, etc. to reset dependencies
• Fast iteration: Container startup is instant after first image build
• Network access: Uses host networking - no port mapping needed
• System resources: Container has full access to CPU, memory, GPU

Data Management & Cleanup

What Happens If You Delete a Project Directory?

Short answer: Your project data is gone (unless backed up).

Understanding the layers:

Component	Location	What Happens on Delete
Project files	~/Code/your-project/	❌ DELETED - no recovery
Container instance	Docker runtime	✅ Already gone (--rm flag)
Docker image	Docker cache	✅ Still exists (~3.2GB)

Recovery Options

If you deleted a project directory:

• ✅ Git remote exists: git clone to recover
• ✅ Have backups: Restore from backup
• ❌ No remote/backup: Data is permanently lost

Docker Image Management

The Docker image (project-workbench:latest) persists separately from your projects:

# View Docker images
docker images | grep project-workbench

# Remove the image (if you want to free ~3.2GB)
docker rmi project-workbench:latest

# Rebuild when needed
cd ~/Code && docker-compose build workbench

Note: Deleting the image doesn't affect existing projects - it just means you'll need to rebuild next time you use project.

Best Practices

1. Use git - Initialize repos and push to remote (GitHub, GitLab, etc.)

   cd ~/Code/your-project
   git init
   git remote add origin git@github.com:user/repo.git
   git push -u origin main

2. For experiments - Use /tmp if you don't care about persistence

   cd /tmp/throwaway-test
   project
   # ... experiment ...
   exit
   # Delete whenever: rm -rf /tmp/throwaway-test

3. Clean up Docker - Periodically remove unused images

   docker system prune -a  # Remove all unused images

Security Notes

• Container runs as your user (UID 1000), not root
• Has sudo access inside container (passwordless)
• Network mode is host - no network isolation
• Full GPU access - trusted code only

Author

Lee Hanken Email: github-12-2017-ds8@leehanken.uk GitHub: github.com/macsplit