Skip to content

development.adoc

Latest commit

 

History

History
355 lines (283 loc) · 12.7 KB

development.adoc

File metadata and controls

355 lines (283 loc) · 12.7 KB

Development Guide

Project Tools for Development

  • shellcheck, shfmt - Shell linting/formatting

  • hadolint - Dockerfile linting

  • yamlfmt - YAML formatting

  • actionlint - GitHub Actions linting

  • conform - Commit message validation

Managed by mise (see .mise.toml):

setup
# Install mise and tools
curl https://mise.run | sh
eval "$(mise activate bash)" # or zsh or fish instead of bash - whatever you are installing from
mise install

# Run checks
just verify

Commands

Run just to see all available commands, or use these common recipes:

Quality Verification

just verify                 # Run all quality verifications with summary
just devbase-install-verify # Verify installation is complete and working

Linting (Individual)

just lint-markdown          # Lint markdown files with rumdl
just lint-yaml              # Lint YAML files with yamlfmt
just lint-shell             # Lint shell scripts with shellcheck
just lint-shell-fmt         # Check shell script formatting with shfmt
just lint-actions           # Lint GitHub Actions workflows with actionlint
just lint-secrets           # Check for secrets and sensitive data with gitleaks
just lint-commit            # Validate commit messages with conform

Fixing Issues

just lint-fix               # Fix all auto-fixable issues
just lint-markdown-fix      # Fix markdown issues with rumdl
just lint-yaml-fix          # Fix YAML formatting with yamlfmt
just lint-shell-fmt-fix     # Fix shell script formatting with shfmt

Development Tools

just dev-tools-deps-verify  # Verify required development tools are installed
just dev-tools-install      # Install project development tools (from .mise.toml)
just dev-tools-update       # Update devbase tools

Testing and Verification Scripts

DevBase includes several verification scripts to test functionality:

Network and Proxy Verification

./verify/verify-proxy-access.sh        # Test connectivity to all DevBase dependencies
./verify/verify-proxy-access.sh --help  # Show all options

# Common usage:
./verify/verify-proxy-access.sh --proxy http://proxy:8080  # Test with specific proxy
./verify/verify-proxy-access.sh --no-proxy                # Test direct connection
./verify/verify-proxy-access.sh --download-test           # Test actual file downloads
./verify/verify-proxy-access.sh --no-keepalive            # Disable connection reuse (for problematic proxies)

This script tests connectivity to: - Git hosting services (GitHub, GitLab, Bitbucket, etc.) - Language runtimes (Node.js, Python, Go, Ruby, Java) - Package registries (npm, PyPI, Maven, Cargo, etc.) - Container registries (Docker Hub, GHCR, Quay) - Development tools sources

The --download-test option performs actual file downloads to verify bandwidth and throughput. Use --no-keepalive if experiencing "Proxy Authentication Required" errors with corporate proxies.

Theme Testing

./verify/test-themes.fish              # Preview all available themes in Fish shell

This Fish script allows you to: - Preview all 10 available themes interactively - See how each theme looks with your terminal - Test theme switching functionality - Verify theme application across all supported tools

Note
 This script requires Fish shell to be installed and configured.

Testing Changes

Before testing with a clean user account, you can use the verification scripts to test specific functionality:

  • ./verify/verify-proxy-access.sh - Test network connectivity and proxy configuration

  • ./verify/test-themes.fish - Preview and test theme functionality

  • just verify - Run all code quality checks

  • just devbase-install-verify - Verify installation completeness

Test with Clean User Account

Testing with a fresh user account simulates a real installation without affecting your main account:

# Create test user with sudo privileges
sudo adduser testuser
sudo usermod -aG sudo testuser

# Switch to test user (clean environment)
su -l testuser

# Verify you're logged in as testuser
whoami
# Output: testuser

# As testuser, install as regular

#....

# When done testing, exit back to your user
exit

# Cleanup (optional - removes test user)
sudo deluser --remove-home testuser
Tip
 The -l flag in su -l testuser provides a clean login shell, simulating a fresh user session with no environment passing.

WSL-Specific Testing Notes

When testing in WSL with su -l, you may encounter issues running Windows executables (like VS Code) because WSL interop is disabled by default. To preserve WSL interoperability while switching users:

# Switch to test user with preserved WSL environment
su -l testuser \
  --whitelist-environment=WSL_INTEROP,WSLENV,WSL_DISTRO_NAME,WSL2_GUI_APPS_ENABLED,LANG

# Now Windows executables will work from the test user context
# For example, VS Code extension installation will work properly

The --whitelist-environment option preserves the specified environment variables even with -l (login shell), maintaining Windows interoperability while still getting a proper login shell environment.

After Installation, also manually verify that VS Code Extensions are used you will have to make the Remote VS Code Server load from you non default WSL testuser. Currently the only way to make this happen is to

# Set the user when launching a distribution with WSL.
[user]
default=testuser

# Shutdown WSL
wsl --shutdown

# Restart

Code Quality

Before PR:

  1. just verify must pass

  2. Commits must follow Conventional Commits

  3. Sign commits: git commit -s -S

  4. Update documentation if needed

  5. Test your features with a testuser

Conventions

  • Entrypoints use set -uo pipefail (not -e as we don’t want to exit directly); sourced libs avoid mutating shell options

  • Use require_env (in libs/validation.sh) to declare required globals inside libs

  • setup.sh is the entrypoint; call init_env before using shared libs, libs/bootstrap/bootstrap.sh orchestrates bootstrap while libs/bootstrap/bootstrap-ui.sh and libs/bootstrap/bootstrap-config.sh provide helpers, libs/install.sh assumes shared libs are sourced there

  • libs/install.sh organizes flow into preflight, configuration, installation, and finalize phases

  • Repo persistence logic lives in libs/persist.sh

  • Preflight/config/install phases fail fast; finalize is best-effort

  • Prefer checksum verification for downloads; document any sources that lack checksums

  • XDG Base Directory compliance

  • just verify must pass

Debugging

# Show paths, custom config detection, and proxy settings
export DEBUG=1
./setup.sh

Project Structure

Root Directory

setup.sh                 # Entry point - user interaction
justfile                # Developer commands (lint, test)
.mise.toml              # Project tool versions
libs/                   # Installation and configuration scripts
dot/                    # User config templates (XDG compliant)
devbase_files/          # Additional resources (systemd units, fish functions)
environments/           # Environment variable templates
docs/                   # Documentation (AsciiDoc)
verify/                 # Verification and testing scripts
  verify-proxy-access.sh  # Network/proxy connectivity tester
  test-themes.fish        # Theme preview and testing
  verify-install-check.sh # Installation verification
  verify-base-lib.sh      # Library function tests
development/            # Development utilities
  just/                 # Just task runner recipes (linters, checks)
  devcerts/             # Local development certificates (mkcert)

Scripts (libs/)

# Core utilities
utils.sh                      # Shared functions (logging, errors, backups)
define-colors.sh              # Color definitions
ui/ui-helpers.sh              # Progress display functions
ui/ui-messages.sh             # UI message catalog
handle-network.sh             # Download and proxy handling

# Pre-installation
bootstrap/bootstrap.sh         # Bootstrap orchestrator
bootstrap/bootstrap-config.sh  # Environment/config helpers
bootstrap/bootstrap-ui.sh      # Bootstrap UI helpers
check-requirements.sh          # OS/disk/sudo/network checks
collect-user-preferences.sh    # Interactive prompts

# Installation
install.sh                    # Main orchestrator
install-apt.sh                # APT packages (security, containers, etc.)
install-snap.sh               # Snap packages (ghostty, chromium)
install-mise.sh               # mise tool manager
install-custom.sh             # Custom binaries (oc, kubectl, dbeaver, intellij, etc.)
install-certificates.sh       # CA certificate installation

# Configuration
process-templates.sh          # Template variable substitution
configure-ssh-git.sh          # SSH keys, git config, GPG signing
configure-shell.sh            # Fish shell setup
configure-completions.sh      # Shell completions (kubectl, gh, etc.)
configure-theme.sh            # Theme application (8 themes across 4 families)
configure-services.sh         # Systemd user services
setup-vscode.sh               # VSCode/Cursor configuration

Configurations (dot/)

.config/
├── devbase/            # DevBase metadata (packages.yaml - unified package configuration)
├── fish/               # Fish shell configuration
│   ├── config.fish     # Main configuration
│   ├── conf.d/         # Configuration directory
│   │   ├── 00-*.fish   # DevBase managed (overwritten)
│   │   ├── 01-*.fish   # DevBase managed (overwritten)
│   │   ├── 02-*.fish   # DevBase managed (overwritten)
│   │   └── 10-*.fish   # User personal configs (preserved)
│   └── functions/      # Fish functions
├── git/                # Git global config
│   ├── config          # Global git configuration
│   └── .gitignore      # Global gitignore
├── ssh/                # SSH config layering
│   ├── custom.config   # Organization-provided hosts
│   └── user.config     # User personal hosts (highest priority)
├── nvim/               # Neovim/LazyVim configuration
├── starship/           # Starship prompt theme
├── zellij/             # Terminal multiplexer config
├── mise/               # Tool version management (config.toml)
├── btop/               # System monitor theme
├── delta/              # Git diff viewer themes
├── eza/                # Modern ls replacement config
├── lazygit/            # Git TUI configuration
├── devtools/           # Development tools settings
└── systemd/user/       # User systemd services

.local/
├── bin/                # User binaries (in PATH)
└── share/
    └── devbase/
        └── backup/     # Automatic backups before overwriting

.ssh/
├── config              # SSH client main config (includes custom.config, user.config)
└── known_hosts         # Pre-populated known hosts

Additional Resources (devbase_files/)

devbase_files/
├── systemd/            # Systemd unit files
│   └── user/           # User services (podman, wayland-socket-symlink)
├── fish-functions/     # Conditionally installed Fish functions
│   └── devbase-proxy.fish  # Proxy management (only if DEVBASE_PROXY_HOST/PORT set)
├── certificates-example/ # Example CA certificates
├── sudo-keep-proxyenv/ # Sudoers config for proxy preservation
├── systemd/            # Systemd unit files
│   └── user/           # User services (podman, wayland-socket-symlink)
└── unattended-upgrades-debian/ # Security update configuration

Custom Configuration (devbase-custom-config/)

Optional organization overlay structure:

devbase-custom-config/  # Optional organization overlay
├── config/
│   └── org.env         # Organization environment variables
├── certificates/       # Organization CA certificates
│   ├── *.crt           # Certificate files
│   └── README.md       # Installation instructions
├── templates/          # Configuration overrides
│   ├── .config/        # XDG config overrides
│   └── .ssh/           # SSH config overrides
├── ssh/                # SSH keys and config
│   └── custom.config   # Organization SSH hosts
└── hooks/              # Lifecycle hooks
    ├── pre-install.sh        # Before installation
    ├── post-configuration.sh # After config, before tools
    └── post-install.sh       # After everything