Skip to content

QUICKSTART.md

Latest commit

 

History

History
216 lines (155 loc) · 5.14 KB

QUICKSTART.md

File metadata and controls

216 lines (155 loc) · 5.14 KB

Quick Start Guide

🚀 Get Started in 5 Minutes

1. Build the Extension

cd dalec-docker-extension
make build-extension
# or
docker buildx build -t dalec-extension:latest . --load

2. Install in Docker Desktop

make install-extension
# or
docker extension install dalec-extension:latest -f

3. Open the Extension

  1. Open Docker Desktop
  2. Click on "Dalec" in the left sidebar
  3. You should see the Dalec Minimal Image Builder interface

4. Build Your First Image

Simple Example: Bash-only Image

  1. Image Name: my-first-minimal:v1
  2. OS Target: azlinux3 (default)
  3. Packages: Check ☑️ bash only
  4. Click "Create Image"

Watch the logs stream in real-time! When complete, you'll see a green success banner.

5. Test the Built Image

Click the "🚀 Run Image" button, or test manually:

# Verify image exists
docker images | grep my-first-minimal

# Run it interactively
docker run -it my-first-minimal:v1 /bin/bash

# Inside the container
echo "Hello from Dalec!"
exit

# Clean up
docker rmi my-first-minimal:v1

📖 Build Examples

Example 1: Minimal Web Server Base

Image Name: web-base:minimal
OS Target: azlinux3
Packages: ☑️ curl, ☑️ bash

Result: ~50MB image with curl + bash + dependencies

Example 2: Ultra-Minimal

Image Name: ultra-minimal:v1
OS Target: azlinux3
Packages: ☑️ bash

Result: Smallest possible image with just bash

Example 3: Multi-Package

Image Name: dev-tools:v1
OS Target: azlinux3
Packages: ☑️ curl, ☑️ bash (add more as available)

Result: Development-ready minimal image

🎯 Tips & Tricks

Tip 1: Watch the Command Preview

The "Command Preview" section shows the exact docker build command being executed. Copy it to run builds from CLI:

# Example command (generated by extension)
docker build -t my-image:v1 \
  --build-arg BUILDKIT_SYNTAX=ghcr.io/project-dalec/dalec/frontend:latest \
  --target=azlinux3/container/depsonly \
  -<<<"$(jq -c '.dependencies.runtime = {\"curl\":{},\"bash\":{}} | .image.entrypoint = \"/bin/bash\"' <<<"{}" )"

Tip 2: Use Auto-Scroll

During long builds, uncheck "Auto-scroll" to examine specific log lines. Re-check to jump back to the latest output.

Tip 3: Clear Logs Between Builds

Click "Clear Logs" before starting a new build for a fresh view.

Tip 4: Copy Image Names

After a successful build, use the "📋 Copy Image Name" button to quickly get the exact image name for CLI commands.

Tip 5: Inspect Before Running

Click "🔍 Inspect" to see image size and metadata before running it.

🔧 Development Mode

Frontend Hot Reload

cd ui
npm install
npm run dev
# In another terminal:
docker extension dev ui-source dalec-extension:latest http://localhost:3000

Now edit ui/src/App.jsx and see changes instantly!

Backend Debugging

cd backend
npm install
npm start
# Backend runs on port 8080

Enable Dev Tools

docker extension dev debug dalec-extension:latest

Click the extension tab to open Chrome DevTools.

🐛 Troubleshooting

Problem: "Docker daemon not running"

Solution: Start Docker Desktop

Problem: "Build fails immediately"

Solution: Check if BuildKit is enabled:

docker buildx ls

Problem: "Extension doesn't appear"

Solution: Restart Docker Desktop after installation

Problem: "Logs show permission denied"

Solution: Ensure Docker has necessary permissions:

docker ps  # Should work without sudo

Problem: "Build hangs"

Solution: First build pulls Dalec frontend image (can take 2-5 min). Subsequent builds are faster.

📊 What's Happening Behind the Scenes?

When you click "Create Image":

  1. Backend receives your configuration
  2. Generates a Dalec spec inline (JSON with runtime dependencies)
  3. Spawns docker build with Dalec BuildKit frontend
  4. Dalec analyzes package dependencies
  5. Creates minimal rootfs with only required files
  6. Builds optimized container image
  7. Streams all output back to UI in real-time
  8. Saves image to local Docker registry

The result: Minimal images with only what you selected + their dependencies!

📚 Next Steps

💡 Ideas to Try

  1. Compare Sizes: Build two images with different package sets and compare sizes
  2. Custom Naming: Use meaningful tags like my-app:base-v1.0.0
  3. Build Templates: Keep notes of successful configurations for reuse
  4. Registry Push: (Coming soon) Push to your registry after building
  5. Multi-Stage: (Coming soon) Use built images as base for app images

❓ Need Help?

  • Check logs in the extension for errors
  • Verify Docker Desktop is running
  • Ensure BuildKit is enabled
  • Review the command preview for syntax issues
  • Look for error messages (highlighted in red) in logs

Happy building! 🎉