Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .devcontainer/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ This devcontainer provides a complete development environment for the Docker Inf
3. Use Command Palette: `Remote-Containers: Reopen in Container`

The initial setup will take a few minutes to:

- Pull the base Debian image
- Install all required tools and dependencies
- Configure the development environment
Expand Down Expand Up @@ -111,6 +112,7 @@ The devcontainer has access to the entire repository:
### VS Code Settings

The devcontainer configures:

- Format on save
- LF line endings
- YAML indentation (2 spaces)
Expand All @@ -120,6 +122,7 @@ The devcontainer configures:
### Docker-in-Docker

The container runs Docker-in-Docker to support:

- Testing Docker installations
- Running Docker Compose modules
- Container-based testing
Expand Down Expand Up @@ -156,6 +159,7 @@ ls /usr/local/lib/bats/
### Slow Container Startup

First-time setup takes longer due to:

- Installing Ansible and dependencies
- Downloading Ansible collections/roles
- Installing Bats framework
Expand Down
12 changes: 6 additions & 6 deletions .devcontainer/post-create.sh
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ echo "🚀 Setting up Docker Infrastructure development environment..."
# Set Docker socket permissions
echo "🐳 Configuring Docker permissions..."
sudo groupadd -f docker --gid 780 # Note: this group ID aligns with the docker_group role
sudo groupmod -g 780 docker # In case the group already existed with a different GID
sudo groupmod -g 780 docker # In case the group already existed with a different GID
sudo usermod -aG docker vscode
check_docker_sock || exit 1

Expand Down Expand Up @@ -85,11 +85,11 @@ echo ""

# Check if Docker is usable without sudo in THIS session
if ! docker info >/dev/null 2>&1; then
echo "⚠️ Docker is not accessible in this session."
echo " You were likely added to the 'docker' group after this shell started."
echo " Run: sudo su - \$USER"
echo " (or reopen the terminal) to refresh group membership."
echo ""
echo "⚠️ Docker is not accessible in this session."
echo " You were likely added to the 'docker' group after this shell started."
echo " Run: sudo su - \$USER"
echo " (or reopen the terminal) to refresh group membership."
echo ""
fi

echo "Quick commands:"
Expand Down
21 changes: 21 additions & 0 deletions .editorconfig
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
; https://editorconfig.org/

root = true

[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

[*.md]
indent_size = 4
trim_trailing_whitespace = false

[*.sh]
indent_size = 4

[*.py]
indent_size = 4
22 changes: 22 additions & 0 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,13 @@ This is an Ansible-based infrastructure automation repository that manages Docke
## Key Commands

### Important: Always Use Task Runner

When suggesting commands to the user, **always prefer `task` commands** from `Taskfile.yml` over raw commands. Only fall back to raw commands if no equivalent task exists. Run `task --list` to discover available tasks.

### Important: Always Use mise for Tool Management

When installing or managing tool versions (Python, Ansible, ansible-lint, yamllint, Bats, Task, etc.), **always use `mise`** instead of `pip install`, `apt install`, or other package managers. Tool versions are defined in `.mise.toml` and must stay in sync.

```bash
# Install all tools at versions defined in .mise.toml
mise install
Expand All @@ -34,6 +37,7 @@ mise use pipx:ansible-lint@26.5.0
```

### Task Runner (Recommended)

```bash
# Show all available tasks
task --list
Expand All @@ -58,6 +62,7 @@ task help
```

### Testing

```bash
# Run all Bats tests (with Task)
task test
Expand All @@ -78,6 +83,7 @@ task test:docker
```

### Running Ansible

```bash
# Dry-run with Task
task ansible:check
Expand All @@ -97,6 +103,7 @@ sudo ansible-pull \
```

### Local Development

```bash
# Install all dependencies (with Task)
task install
Expand Down Expand Up @@ -139,6 +146,7 @@ tests/
## Code Conventions

### Ansible Playbooks and Roles

- Use YAML with 2-space indentation
- Follow Ansible best practices for role structure
- All playbooks must start with `---`
Expand All @@ -149,6 +157,7 @@ tests/
- Use `handlers/main.yml` for service restarts

### YAML Style

- Use 2-space indentation (never tabs)
- No trailing whitespace
- End files with a single newline
Expand All @@ -157,12 +166,14 @@ tests/
- Use lowercase for booleans: `true`, `false`

### Naming Conventions

- Roles: lowercase with underscores (e.g., `ansible_pull_setup`)
- Variables: lowercase with underscores (e.g., `server_features`)
- Host names: lowercase (e.g., `svlazext`)
- Tags: lowercase (e.g., `docker`, `traefik`)

### File Organization

- Group related tasks in role subdirectories
- Use `tasks/main.yml` as the entry point for roles
- Split complex roles into separate task files
Expand All @@ -172,6 +183,7 @@ tests/
## Testing Requirements

### Before Making Changes

1. **ALWAYS run tests first**: `./tests/bash/run-tests.sh`
- This is a required step before committing any Ansible or YAML changes
- Fix all test failures before proceeding
Expand All @@ -182,14 +194,17 @@ tests/
- GitHub SSH Keys: `./tests/bash/run-tests.sh --test github-ssh-keys-test.bats`

### After Making Changes

- **All YAML files must pass yamllint** (no errors, warnings acceptable)
- **All Ansible files must pass ansible-lint** (no errors, warnings acceptable)
- Playbooks must pass syntax-check
- GitHub Actions workflow must succeed
- **Run linting again before final commit** to ensure all issues are resolved

### CI/CD Pipeline

The repository uses the [Bats testing framework](https://github.com/bats-core/bats-core) for comprehensive testing:

- Lint checks (yamllint, ansible-lint)
- Syntax validation (Ansible playbooks and shell scripts)
- Docker provisioning tests
Expand All @@ -199,6 +214,7 @@ The repository uses the [Bats testing framework](https://github.com/bats-core/ba
All tests are located in `tests/bash/` and use the Bats test format.

Workflows trigger on:

- Push to `main` or `copilot/**` branches
- Pull requests
- Manual workflow dispatch
Expand All @@ -208,17 +224,20 @@ See [tests/bash/README.md](../tests/bash/README.md) for detailed testing documen
## Important Boundaries

### DO NOT Modify

- `.git/` directory or git history
- LICENSE file (MIT License)
- Production server configurations without explicit approval
- Secrets or credentials (use Ansible Vault if needed)

### DO Modify Carefully

- `ansible/inventory/hosts.yml` - Server inventory (only with clear understanding)
- `ansible/playbooks/main.yml` - Main playbook (ensure backward compatibility)
- GitHub Actions workflows - Test thoroughly before merging

### ALWAYS

- Follow existing code structure and patterns
- Test changes using provided test scripts
- Maintain backward compatibility with existing servers
Expand All @@ -229,6 +248,7 @@ See [tests/bash/README.md](../tests/bash/README.md) for detailed testing documen
## Example Workflows

### Adding a New Ansible Role

1. Create role structure:
```bash
cd ansible/roles
Expand All @@ -253,6 +273,7 @@ See [tests/bash/README.md](../tests/bash/README.md) for detailed testing documen
5. Test with CI pipeline

### Adding a New Server

1. Add to `ansible/inventory/hosts.yml`:
```yaml
NEWSERVER:
Expand All @@ -266,6 +287,7 @@ See [tests/bash/README.md](../tests/bash/README.md) for detailed testing documen
3. Test the configuration

### Modifying Docker Compose Modules

1. Edit module definition in `ansible/roles/docker_compose_modules/vars/modules/`
2. Update role tasks if needed in `ansible/roles/docker_compose_modules/tasks/`
3. Test with: `bash ansible/scripts/tests/docker-test.sh`
Expand Down
26 changes: 26 additions & 0 deletions .yamlfmt.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
---
doublestar: true
formatter:
type: basic
disable_alias_key_correction: true
indent: 2
max_line_length: 120
pad_line_comments: 1
drop_merge_tag: true
eof_newline: true
force_array_style: block
include_document_start: true
line_ending: lf
retain_line_breaks_single: true
scan_folded_as_literal: true
trim_trailing_whitespace: true
# APM-managed / generated files use the tool's own formatting — never hand-edited.
exclude:
- apm.yml
- apm.lock.yaml
- apm_modules/**
# Spec Kit output and Python virtual environments. Listed explicitly rather
# than through gitignore_excludes: without a .gitignore, yamlfmt then lints
# nothing and still exits 0.
- .specify/**
- .venv*/**
22 changes: 22 additions & 0 deletions .yamllint.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
---
extends: default

rules:
# Inline comment spacing varies by author style — not auto-fixable
comments: disable
# Long lines are unavoidable with image digests, Traefik labels, and URLs — not auto-fixable
line-length: disable
# Let yamlfmt handle document start markers
document-start: disable
# Allow 'on:' as a mapping key in GitHub Actions workflows
truthy:
allowed-values:
- "true"
- "false"
check-keys: false

# APM-managed / generated files use the tool's own formatting — never hand-edited.
ignore: |-
apm.yml
apm.lock.yaml
apm_modules/
1 change: 1 addition & 0 deletions INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,7 @@ For svlazext, ensure the following:
For svldev (Development/Management Server), the following steps are largely automated:

**Automated Steps:**

- ✅ Ansible user creation with sudo privileges (`system_setup` role)
- ✅ Docker group membership for specified users (`geerlingguy.docker` role)
- ✅ SSH service configuration (`system_setup` role)
Expand Down
30 changes: 18 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,7 @@ For Ansible documentation and structure, see [ansible/README.md](ansible/README.
### svlazext (Debian)

Primary Docker host configured with:

- ✅ Docker Engine (geerlingguy.docker)
- ✅ UFW Firewall (HTTP, HTTPS, SSH)
- ✅ Chezmoi dotfiles management
Expand All @@ -81,6 +82,7 @@ Primary Docker host configured with:
### svldev (Debian)

Development/management server configured with:

- ✅ Automated system setup (ansible user, sudo, SSH)
- ✅ Docker Engine with user group management (geerlingguy.docker)
- ✅ UFW Firewall (SSH)
Expand Down Expand Up @@ -143,18 +145,18 @@ task help

### Common Task Commands

| Command | Description |
|---------|-------------|
| `task install` | Install all dependencies (Python, Ansible, Bats) |
| `task test` | Run all tests |
| `task test:lint` | Run linting tests only |
| `task test:syntax` | Run syntax validation tests |
| `task lint` | Run yamllint and ansible-lint |
| `task ansible:check` | Dry-run ansible-pull (no changes) |
| `task ansible:pull` | Run ansible-pull (apply configuration) |
| `task ci:local` | Run full CI pipeline locally |
| `task info` | Display environment information |
| `task help` | Show detailed help and examples |
| Command | Description |
| -------------------- | ------------------------------------------------ |
| `task install` | Install all dependencies (Python, Ansible, Bats) |
| `task test` | Run all tests |
| `task test:lint` | Run linting tests only |
| `task test:syntax` | Run syntax validation tests |
| `task lint` | Run yamllint and ansible-lint |
| `task ansible:check` | Dry-run ansible-pull (no changes) |
| `task ansible:pull` | Run ansible-pull (apply configuration) |
| `task ci:local` | Run full CI pipeline locally |
| `task info` | Display environment information |
| `task help` | Show detailed help and examples |

See [Taskfile.yml](Taskfile.yml) for all available tasks.

Expand All @@ -165,6 +167,7 @@ The repository includes comprehensive testing using the [Bats testing framework]
### Running Tests Locally

With Task (recommended):

```bash
# Run all tests
task test
Expand All @@ -176,6 +179,7 @@ task test:docker
```

Without Task:

```bash
# Run all tests
./tests/bash/run-tests.sh
Expand All @@ -190,6 +194,7 @@ Without Task:
### Test Suite

Tests include:

- **Linting**: yamllint and ansible-lint checks
- **Syntax validation**: Ansible playbooks and shell scripts
- **Docker provisioning**: Installation and configuration
Expand All @@ -201,6 +206,7 @@ See [tests/bash/README.md](tests/bash/README.md) for detailed testing documentat
### CI/CD Pipeline

Tests are automatically run via GitHub Actions on:

- Push to `main` or `copilot/**` branches
- Pull requests
- Manual workflow dispatch
Expand Down
Loading
Loading