Common Tasks¶

Frequently performed operations with the Developer Environment Framework.

Environment Management¶

Create a New Program Environment¶

# Use the Makefile helper
make init-program

# Or manually copy the template
cp -r packages/programs/templates/basic packages/programs/my-project
cd packages/programs/my-project

Start an Environment¶

cd packages/programs/my-project
vagrant up

Stop an Environment¶

vagrant halt          # Graceful shutdown
vagrant suspend       # Save state (faster restart)

Restart an Environment¶

vagrant reload        # Hard restart
vagrant reload --provision  # Restart and re-provision

Delete an Environment¶

vagrant destroy       # Prompts for confirmation
vagrant destroy -f    # Force delete without prompt

Configuration Changes¶

Add a New Tool¶

Edit ansible/group_vars/all.yml:

apps:
  new_tool:
    enabled: true
    version: "1.2.3"

Apply changes:

vagrant provision

Change Tool Version¶

Update version in ansible/group_vars/all.yml:

apps:
  docker:
    version: "24.0"  # Change from 23.0

Re-provision:

vagrant provision

Override Organization Settings¶

In your program's ansible/group_vars/all.yml:

# Override Docker version from organization default
apps:
  docker:
    version: "23.0.6"

# Add program-specific Python packages
apps:
  python:
    packages:
      - requests
      - custom-internal-library

Testing¶

Run All Tests¶

make test

Test Specific Layer¶

make test-base        # Base layer only
make test-org         # Organization layer only

Validate Configuration¶

# Check Ansible syntax
make validate

# Lint playbooks
make lint

FOSS Package Management¶

Search for Packages¶

foss-cli search python
foss-cli search -e python  # Ecosystem filter

View Package Details¶

foss-cli info requests

Check Security Status¶

foss-cli security requests

Submit a Package¶

foss-cli submit \
  --name my-package \
  --version 1.0.0 \
  --ecosystem pypi \
  --license MIT

List All Packages¶

foss-cli list
foss-cli list --status approved

Building Images¶

Build Base Image¶

# Rocky Linux 9 (recommended)
make build-base
make build-base-rocky9

# Rocky Linux 8
make build-base-rocky8

# Build all base images
make build-all

Output:

packages/base/artifacts/base-rocky9.box
packages/base/artifacts/base-rocky8.box

Build Organization Spin¶

make build-org-standard

Build All Layers¶

make build-all

Accessing Environments¶

SSH Into VM¶

Standard Vagrant SSH¶

cd packages/programs/my-project
vagrant ssh

Using vagrant-ssh Wrapper (Recommended)¶

The vagrant-ssh script provides enhanced functionality with auto-discovery:

# SSH to any VM by name from anywhere
./scripts/vagrant-ssh base-rocky9
./scripts/vagrant-ssh standard-devenv

Run Single Command¶

Standard Method¶

vagrant ssh -c "docker ps"
vagrant ssh -c "python3 --version"

Using vagrant-ssh Wrapper¶

# Execute commands from anywhere
./scripts/vagrant-ssh standard-devenv "docker ps"
./scripts/vagrant-ssh base-rocky9 "systemctl status"

# Execute in specific directory
./scripts/vagrant-ssh standard-devenv --workdir /workspace "git status"
./scripts/vagrant-ssh standard-devenv --workdir /vagrant "make test"

Start Shell in Specific Directory¶

# Start interactive shell in /workspace
./scripts/vagrant-ssh standard-devenv --workdir /workspace

Get SSH Config¶

vagrant ssh-config

Use with direct SSH:

vagrant ssh-config > ssh-config
ssh -F ssh-config default

Default Shared Folder¶

The project directory is mounted at /vagrant:

vagrant ssh
ls /vagrant  # Your project files

Add Custom Shared Folders¶

Edit Vagrantfile:

config.vm.synced_folder "./data", "/data"

Networking¶

Access Services from Host¶

Forward ports in Vagrantfile:

config.vm.network "forwarded_port", guest: 8000, host: 8000

Apply changes:

vagrant reload

Check VM IP¶

vagrant ssh -c "ip addr show"

Troubleshooting¶

Re-provision Failed Setup¶

vagrant provision

View Ansible Output¶

vagrant up --provision --debug

Reset to Clean State¶

vagrant destroy -f
vagrant up

Check VM Status¶

vagrant status          # Current project
vagrant global-status   # All VMs

Clean Up Old VMs¶

vagrant global-status --prune

Backup and Restore¶

Export VM State¶

vagrant halt
vagrant package --output my-backup.box

Restore from Backup¶

vagrant box add my-backup my-backup.box

Update Vagrantfile:

config.vm.box = "my-backup"

Documentation¶

Build Docs Locally¶

make docs

Output: docs/site/

Serve Docs Locally¶

make serve-docs

Browse to: http://localhost:8000

Maintenance¶

Clean Vagrant Files¶

make clean

Remove Built Artifacts¶

make clean-artifacts

Update Vagrant Boxes¶

vagrant box update
vagrant box prune  # Remove old versions

Advanced Operations¶

Use Different Provider¶

vagrant up --provider=vmware_desktop
vagrant up --provider=libvirt

Set Resource Limits¶