Skip to content

Commit 8d5164c

Browse files
Copilotbbj4t
Copilot
and
bbj4t
committed
Add comprehensive Copilot instructions for repository
Co-authored-by: bbj4t <218265450+bbj4t@users.noreply.github.com>
1 parent be6627a commit 8d5164c

1 file changed

Lines changed: 226 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
# GitHub Copilot Instructions for Windows-in-Docker
2+
3+
## Project Overview
4+
5+
This repository contains a Docker-based Windows virtualization solution that runs Windows inside a Docker container using QEMU/KVM. The project enables users to run various Windows versions (from Windows 2000 to Windows 11 and Server editions) in a containerized environment with web-based viewing and RDP access.
6+
7+
## Technology Stack
8+
9+
- **Primary Language**: Bash shell scripts
10+
- **Virtualization**: QEMU/KVM
11+
- **Containerization**: Docker, Docker Compose, Kubernetes
12+
- **Base Image**: qemux/qemu
13+
- **Key Dependencies**: Samba, wimtools, dos2unix, cabextract, libxml2-utils
14+
15+
## Project Structure
16+
17+
- `src/`: Core shell scripts that handle installation, configuration, and runtime
18+
- `entry.sh`: Main entry point that orchestrates the startup process
19+
- `define.sh`: Version definitions and Windows edition mappings (1944 lines)
20+
- `install.sh`: Windows installation automation (1336 lines)
21+
- `mido.sh`: Windows ISO download functionality (834 lines)
22+
- `power.sh`: Power management and shutdown handling (241 lines)
23+
- `samba.sh`: Samba file sharing configuration (228 lines)
24+
- `assets/`: XML configuration files for automated Windows installations (unattended.xml files)
25+
- `.github/workflows/`: CI/CD workflows for building, testing, and releasing
26+
- `Dockerfile`: Multi-stage Docker build configuration
27+
- `compose.yml`: Docker Compose configuration example
28+
- `kubernetes.yml`: Kubernetes deployment configuration
29+
30+
## Coding Standards
31+
32+
### Shell Script Standards
33+
34+
1. **Shebang and Options**:
35+
- Always use `#!/usr/bin/env bash` as the shebang
36+
- Enable strict error handling: `set -Eeuo pipefail`
37+
- This ensures scripts exit on errors, undefined variables, and pipe failures
38+
39+
2. **ShellCheck Compliance**:
40+
- All shell scripts must pass ShellCheck validation
41+
- Excluded checks (as per workflow configuration):
42+
- SC1091: Not following sourced files
43+
- SC2001: Regex usage patterns
44+
- SC2002: Useless cat usage
45+
- SC2034: Unused variables
46+
- SC2064: Quoting in traps
47+
- SC2153: Variable name typos
48+
- SC2317: Unreachable commands
49+
- SC2028: Echo patterns
50+
- Run ShellCheck with: `shellcheck -x --source-path=src -e SC1091 -e SC2001 -e SC2002 -e SC2034 -e SC2064 -e SC2153 -e SC2317 -e SC2028 src/*.sh`
51+
52+
3. **Variable Declarations**:
53+
- Use parameter expansion with defaults: `: "${VAR:="default_value"}"`
54+
- Quote all variable references: `"$VAR"` not `$VAR`
55+
- Use lowercase with case-insensitive matching: `"${VERSION,,}"`
56+
57+
4. **Function Definitions**:
58+
- Use descriptive function names in camelCase (e.g., `parseVersion`, `downloadImage`)
59+
- Document complex functions with comments explaining their purpose
60+
61+
5. **Error Handling**:
62+
- Use `error` function for error messages (defined in utils.sh)
63+
- Use `info` function for informational messages
64+
- Check command exit codes explicitly when needed
65+
66+
### Docker and Configuration Files
67+
68+
1. **Dockerfile**:
69+
- Use syntax directive: `# syntax=docker/dockerfile:1`
70+
- Follow hadolint best practices
71+
- Excluded hadolint checks: DL3006 (FROM version), DL3008 (apt-get pinning)
72+
- Always clean up apt cache: `rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*`
73+
74+
2. **XML Files**:
75+
- Must be valid XML (validated in CI)
76+
- Located in `assets/` directory
77+
- Named according to Windows version pattern: `win{version}x{arch}-{edition}.xml`
78+
79+
3. **JSON/YAML Files**:
80+
- Must pass JSON/YAML validation
81+
- Kubernetes YAML files are excluded from validation regex
82+
83+
## Build and Test Process
84+
85+
### Linting
86+
87+
The repository uses multiple linters in the check workflow:
88+
89+
```bash
90+
# Run all checks (matches CI)
91+
# This uses the check.yml workflow which runs:
92+
# 1. ShellCheck on all .sh files
93+
shellcheck -x --source-path=src -e SC1091 -e SC2001 -e SC2002 -e SC2034 -e SC2064 -e SC2153 -e SC2317 -e SC2028 src/*.sh
94+
95+
# 2. Hadolint on Dockerfile
96+
hadolint Dockerfile --ignore DL3006 --ignore DL3008
97+
98+
# 3. XML validation on assets
99+
# (requires xml linter tool)
100+
101+
# 4. JSON/YAML validation
102+
# (requires json-yaml-validate tool)
103+
```
104+
105+
### Building
106+
107+
```bash
108+
# Build the Docker image locally
109+
docker build -t windows:local .
110+
111+
# Build with Docker Compose
112+
docker compose build
113+
```
114+
115+
### Testing
116+
117+
The repository includes a test workflow (`test.yml`) for basic functionality testing. Always test changes by:
118+
119+
1. Building the Docker image
120+
2. Running the container with basic configuration
121+
3. Verifying startup and initialization logs
122+
4. Testing specific features affected by your changes
123+
124+
## Key Concepts and Conventions
125+
126+
### Windows Version Handling
127+
128+
- The `VERSION` environment variable controls which Windows version to download/install
129+
- Version aliases are extensive (e.g., "11", "win11", "windows 11" all map to "win11x64")
130+
- Version parsing happens in `define.sh` - be careful when modifying version logic
131+
132+
### Automatic Installation
133+
134+
- The project performs fully automated Windows installations
135+
- Unattended XML files in `assets/` directory configure Windows setup
136+
- Installation scripts handle drivers, language settings, and user creation
137+
- Default credentials: username "Docker", password "admin"
138+
139+
### File Organization
140+
141+
- Runtime scripts are sourced in sequence from `entry.sh`
142+
- Scripts use shared utility functions from `utils.sh`
143+
- Configuration is passed via environment variables
144+
145+
### Environment Variables
146+
147+
Key environment variables include:
148+
- `VERSION`: Windows version to install
149+
- `DISK_SIZE`: Virtual disk size (default 64GB)
150+
- `RAM_SIZE`: RAM allocation (default 4GB)
151+
- `CPU_CORES`: CPU core count (default 2)
152+
- `USERNAME`/`PASSWORD`: Windows user credentials
153+
- `LANGUAGE`: Windows language (default English)
154+
- `KEYBOARD`/`REGION`: Locale settings
155+
156+
## Security Considerations
157+
158+
1. **Never commit secrets**: No API keys, passwords, or tokens in code
159+
2. **Use GitHub Secrets**: Sensitive data in workflows must use repository secrets
160+
3. **Validate inputs**: Always validate and sanitize environment variables
161+
4. **Quote variables**: Prevent injection attacks by properly quoting shell variables
162+
5. **Minimal permissions**: Follow principle of least privilege in Docker configurations
163+
164+
## Pull Request and Contribution Guidelines
165+
166+
1. **Keep changes minimal**: Make surgical, focused changes
167+
2. **Test thoroughly**: Verify your changes don't break existing functionality
168+
3. **Update documentation**: If adding features or changing behavior, update README.md
169+
4. **Follow existing patterns**: Match the coding style of existing files
170+
5. **Lint before committing**: Run ShellCheck and other linters on your changes
171+
6. **Descriptive commits**: Write clear commit messages explaining what and why
172+
173+
## Common Tasks
174+
175+
### Adding a New Windows Version
176+
177+
1. Add version alias mapping in `define.sh` (in the `parseVersion` function)
178+
2. Create corresponding XML unattended file in `assets/`
179+
3. Test the download and installation process
180+
4. Update README.md with new version in the table
181+
182+
### Modifying Installation Process
183+
184+
1. Changes typically go in `install.sh`
185+
2. Ensure compatibility with all supported Windows versions
186+
3. Test with at least Windows 10 and 11
187+
4. Verify unattended installation still works
188+
189+
### Updating Dependencies
190+
191+
1. Modify `Dockerfile` apt-get packages
192+
2. Test Docker build succeeds
193+
3. Verify container still functions correctly
194+
4. Update version if needed
195+
196+
## Documentation
197+
198+
- Main documentation is in `README.md`
199+
- Keep FAQ section updated with common questions
200+
- Include examples for new features
201+
- Update version tables when adding support for new Windows versions
202+
203+
## Workflow and CI/CD
204+
205+
- **Build workflow**: Builds and publishes Docker images to Docker Hub and GHCR
206+
- **Check workflow**: Runs linters and validation (ShellCheck, hadolint, XML, JSON/YAML)
207+
- **Test workflow**: Runs basic functionality tests
208+
- **Review workflow**: Handles code review automation
209+
210+
Always ensure CI checks pass before merging changes.
211+
212+
## Additional Resources
213+
214+
- QEMU documentation: https://www.qemu.org/docs/master/
215+
- Windows unattended installation: https://learn.microsoft.com/en-us/windows-hardware/customize/desktop/unattend/
216+
- Docker best practices: https://docs.docker.com/develop/dev-best-practices/
217+
- Bash best practices: https://www.gnu.org/software/bash/manual/
218+
219+
## Notes for Copilot
220+
221+
- This is a specialized virtualization project - understand QEMU and Windows installation concepts
222+
- Shell scripts are complex and interdependent - be cautious with changes
223+
- The project serves a large user base - stability and compatibility are critical
224+
- Always consider the impact on different Windows versions (7, 8, 10, 11, Server editions)
225+
- Performance matters - container startup and Windows installation should be optimized
226+
- Error messages should be clear and actionable for end users

0 commit comments

Comments
 (0)