From d78e099eed349c72180ace14b7123433e92a64ef Mon Sep 17 00:00:00 2001 From: gerchowl Date: Mon, 10 Nov 2025 20:34:23 +0000 Subject: [PATCH 1/3] feat(devcontainer): add podman-compose.yml for direct Podman usage Add podman-compose.yml configuration file to support users who prefer using Podman Compose instead of VS Code's built-in devcontainer support. Configuration includes: - Proper volume mount with cached consistency - Working directory set to /workspace - Interactive terminal support (stdin_open, tty) - Matches devcontainer.json settings This provides a declarative alternative to direct Podman CLI usage while maintaining compatibility with the devcontainer setup. Related to #24 --- podman-compose.yml | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 podman-compose.yml diff --git a/podman-compose.yml b/podman-compose.yml new file mode 100644 index 0000000..a7cab77 --- /dev/null +++ b/podman-compose.yml @@ -0,0 +1,10 @@ +version: '3' +services: + dev: + image: ghcr.io/morepet/containers/dev/typst:1.3-dev + volumes: + - .:/workspace:cached + working_dir: /workspace + command: /bin/bash + stdin_open: true + tty: true From 553d46fe9dadd894e7bf11717014a8833d134284 Mon Sep 17 00:00:00 2001 From: gerchowl Date: Mon, 10 Nov 2025 20:34:59 +0000 Subject: [PATCH 2/3] docs(readme): add comprehensive Podman usage documentation Add new section 'Using Podman Without VS Code Devcontainer' with three detailed options for using the devcontainer with Podman directly: Option 1: Direct Podman CLI Usage - Command-line usage with proper volume mounts - SELinux context handling (:Z flag) for Linux systems - Manual initialization script execution order - Pros/cons comparison Option 2: Podman Compose - Installation instructions for multiple platforms - Usage with podman-compose.yml file - Start/stop commands and workflow - Benefits of declarative configuration Option 3: Dev Container CLI - Official devcontainers/cli installation - Full devcontainer.json compatibility with --docker-path podman - Automatic lifecycle script execution - Complete feature support Additional documentation includes: - Comparison table of all three options - Recommendations for different use cases - Proper script execution order (post-create.sh, post-attach.sh) - SELinux considerations for Linux users - Links to Quick Start for VS Code integration This provides flexibility for users who prefer different workflows while maintaining full compatibility with the devcontainer setup. Fixes #24 --- README.md | 185 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 185 insertions(+) diff --git a/README.md b/README.md index 6542fca..2d2806c 100644 --- a/README.md +++ b/README.md @@ -237,6 +237,191 @@ Open your browser to to see: That's it! The build system handles everything automatically. +## Using Podman Without VS Code Devcontainer + +If you prefer to use Podman directly instead of VS Code's built-in devcontainer support, you have three options. +All options assume you've completed the [Host Machine Prerequisites](#host-machine-prerequisites) (especially GHCR authentication). + +### Option 1: Direct Podman CLI Usage + +Use Podman command-line directly for maximum control and minimal dependencies. + +**Start the container:** + +```bash +# Linux (with SELinux context) +podman run -it --rm \ + -v "${PWD}:/workspace:Z" \ + -w /workspace \ + ghcr.io/morepet/containers/dev/typst:1.3-dev \ + /bin/bash + +# macOS/Windows (no SELinux) +podman run -it --rm \ + -v "${PWD}:/workspace" \ + -w /workspace \ + ghcr.io/morepet/containers/dev/typst:1.3-dev \ + /bin/bash +``` + +**Important: SELinux Context (Linux only)** + +The `:Z` flag is required on Linux systems with SELinux to allow the container to access the mounted volume. Without it, you'll get permission denied errors. + +- `:Z` - Private unshared label (recommended for single container access) +- `:z` - Shared label (use if multiple containers need access) + +**Inside the container, run initialization scripts in order:** + +```bash +# 1. Post-create (one-time setup) +/workspace/.devcontainer/post-create.sh + +# 2. Post-attach (session setup) +/workspace/.devcontainer/post-attach.sh + +# 3. Build documentation +make +``` + +**Script execution order matters:** +1. `post-create.sh` - Sets up git, GitHub CLI, pre-commit hooks, Node.js +2. `post-attach.sh` - Configures git and verifies GitHub CLI for current session + +**Pros:** +- No additional tools required beyond Podman +- Full control over container lifecycle +- Easy to customize and script + +**Cons:** +- Manual script execution required +- Need to remember the correct command and flags +- No automatic devcontainer.json integration + +### Option 2: Podman Compose + +Use `podman-compose` for a more declarative approach with persistent configuration. + +**Install podman-compose:** + +```bash +# Using pip +pip install podman-compose + +# Or using system package manager (Fedora/RHEL) +sudo dnf install podman-compose + +# Or using system package manager (Debian/Ubuntu) +sudo apt install podman-compose +``` + +**Start the container:** + +```bash +# Start in detached mode +podman-compose up -d + +# Attach to the running container +podman-compose exec dev /bin/bash +``` + +**Inside the container, run initialization scripts:** + +```bash +# Run setup scripts in order +/workspace/.devcontainer/post-create.sh +/workspace/.devcontainer/post-attach.sh + +# Build documentation +make +``` + +**Stop the container:** + +```bash +podman-compose down +``` + +**Configuration file:** The repository includes `podman-compose.yml` with proper settings: +- Volume mount with cached consistency +- Working directory set to `/workspace` +- Interactive terminal support +- Matches devcontainer.json configuration + +**Pros:** +- Declarative configuration in `podman-compose.yml` +- Easy to start/stop with simple commands +- Persistent container state (optional) +- Familiar Docker Compose syntax + +**Cons:** +- Requires installing podman-compose +- Still need to manually run initialization scripts +- Limited devcontainer.json feature support + +### Option 3: Dev Container CLI + +Use the official Dev Container CLI for full `devcontainer.json` compatibility with Podman. + +**Install Dev Container CLI:** + +```bash +npm install -g @devcontainers/cli +``` + +**Start the devcontainer with Podman:** + +```bash +# Build and start the devcontainer +devcontainer up --workspace-folder . --docker-path podman + +# Execute commands inside +devcontainer exec --workspace-folder . make + +# Open a shell +devcontainer exec --workspace-folder . /bin/bash +``` + +**Full integration:** + +The Dev Container CLI automatically: +- ✅ Reads and applies `.devcontainer/devcontainer.json` settings +- ✅ Runs `initializeCommand` on the host +- ✅ Executes `postCreateCommand` and `postAttachCommand` in container +- ✅ Mounts volumes correctly +- ✅ Installs VS Code extensions (when used with VS Code) + +**Pros:** +- **Best option for full compatibility** with devcontainer.json +- Automatic script execution in correct order +- Supports all devcontainer features (extensions, settings, lifecycle scripts) +- Works with Podman via `--docker-path` flag +- Can be used in CI/CD pipelines + +**Cons:** +- Requires Node.js and npm +- More complex installation +- Slight learning curve for CLI commands + +### Comparison Table + +| Feature | Direct CLI | Podman Compose | Dev Container CLI | +|---------|------------|----------------|-------------------| +| **Setup Complexity** | Low | Medium | Medium | +| **Dependencies** | Podman only | Podman + podman-compose | Podman + Node.js + npm | +| **Script Automation** | Manual | Manual | Automatic ✅ | +| **devcontainer.json Support** | None | None | Full ✅ | +| **Flexibility** | Highest | High | Medium | +| **Best For** | Quick tests, scripting | Persistent dev environments | Full devcontainer compatibility | + +### Recommendation + +- **Use Option 1 (Direct CLI)** for quick testing or one-off builds +- **Use Option 2 (Podman Compose)** if you prefer docker-compose workflow +- **Use Option 3 (Dev Container CLI)** for the most complete devcontainer experience + +**Still prefer VS Code integration?** See [Quick Start](#quick-start) for using VS Code's built-in Dev Containers extension, which provides the best IDE integration. + ## Features ### Documentation Generation From 572190d7b817fc83b7a61cfb2e6c8f10b2a004c1 Mon Sep 17 00:00:00 2001 From: gerchowl Date: Mon, 10 Nov 2025 20:35:32 +0000 Subject: [PATCH 3/3] docs(changelog): add entry for Podman usage documentation Document addition of comprehensive Podman usage guide with three options for using the devcontainer without VS Code: - Direct Podman CLI with SELinux considerations - Podman Compose with declarative configuration - Dev Container CLI for full compatibility Related to #24 --- CHANGELOG.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0dae43a..b53a2f3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,21 @@ All notable changes to this template will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [Unreleased] + +### Added + +- **Podman Usage Documentation** + - Comprehensive guide for using devcontainer with Podman without VS Code (#24) + - Three usage options: Direct CLI, Podman Compose, and Dev Container CLI + - `podman-compose.yml` configuration file for declarative container management + - Detailed comparison table of all three Podman usage options + - SELinux context handling documentation for Linux users (`:Z` flag) + - Proper initialization script execution order (post-create.sh, post-attach.sh) + - Installation instructions for multiple platforms + - Pros/cons analysis for each approach + - Recommendations for different use cases + ## [0.4.1] - 2025-11-10 ### Fixed