chore: reorganize repository structure
- Move docker-compose files to .docker/compose/ - Move docker-entrypoint.sh to .docker/ - Move DOCKER.md to .docker/README.md - Move 16 implementation docs to docs/implementation/ - Delete test artifacts (block_test.txt, caddy_*.json) - Update all references in Dockerfile, Makefile, tasks, scripts - Add .github/instructions/structure.instructions.md for enforcement - Update CHANGELOG.md Root level reduced from 81 items to ~35 visible items.
This commit is contained in:
GitHub Actions
@@ -0,0 +1,94 @@
|
||||
---
|
||||
applyTo: '*'
|
||||
description: 'Repository structure guidelines to maintain organized file placement'
|
||||
---
|
||||
|
||||
# Repository Structure Guidelines
|
||||
|
||||
## Root Level Rules
|
||||
|
||||
The repository root should contain ONLY:
|
||||
|
||||
- Essential config files (`.gitignore`, `.pre-commit-config.yaml`, `Makefile`, etc.)
|
||||
- Standard project files (`README.md`, `CONTRIBUTING.md`, `LICENSE`, `CHANGELOG.md`)
|
||||
- Go workspace files (`go.work`, `go.work.sum`)
|
||||
- VS Code workspace (`Chiron.code-workspace`)
|
||||
- Primary `Dockerfile` (entrypoint and compose files live in `.docker/`)
|
||||
|
||||
## File Placement Rules
|
||||
|
||||
### Implementation/Feature Documentation
|
||||
|
||||
- **Location**: `docs/implementation/`
|
||||
- **Pattern**: `*_SUMMARY.md`, `*_IMPLEMENTATION.md`, `*_COMPLETE.md`, `*_FEATURE.md`
|
||||
- **Never** place implementation docs at root
|
||||
|
||||
### Docker Compose Files
|
||||
|
||||
- **Location**: `.docker/compose/`
|
||||
- **Files**: `docker-compose.yml`, `docker-compose.*.yml`
|
||||
- **Override**: Local overrides go in `.docker/compose/docker-compose.override.yml` (gitignored)
|
||||
- **Exception**: `docker-compose.override.yml` at root is allowed for backward compatibility
|
||||
|
||||
### Docker Support Files
|
||||
|
||||
- **Location**: `.docker/`
|
||||
- **Files**: `docker-entrypoint.sh`, Docker documentation (`README.md`)
|
||||
|
||||
### Test Artifacts
|
||||
|
||||
- **Never commit**: `*.sarif`, `*_test.txt`, `*.cover` files at root
|
||||
- **Location**: Test outputs should go to `test-results/` or be gitignored
|
||||
|
||||
### Debug/Temp Config Files
|
||||
|
||||
- **Never commit**: Temporary JSON configs like `caddy_*.json` at root
|
||||
- **Location**: Use `configs/` for persistent configs, gitignore temp files
|
||||
|
||||
### Scripts
|
||||
|
||||
- **Location**: `scripts/` for general scripts
|
||||
- **Location**: `.github/skills/scripts/` for agent skill scripts
|
||||
|
||||
## Before Creating New Files
|
||||
|
||||
Ask yourself:
|
||||
|
||||
1. Is this a standard project file? → Root is OK
|
||||
2. Is this implementation documentation? → `docs/implementation/`
|
||||
3. Is this Docker-related? → `.docker/` or `.docker/compose/`
|
||||
4. Is this a test artifact? → `test-results/` or gitignore
|
||||
5. Is this a script? → `scripts/`
|
||||
6. Is this runtime config? → `configs/`
|
||||
|
||||
## Directory Structure Reference
|
||||
|
||||
```
|
||||
/
|
||||
├── .docker/ # Docker configuration
|
||||
│ ├── compose/ # All docker-compose files
|
||||
│ └── docker-entrypoint.sh # Container entrypoint
|
||||
├── .github/ # GitHub workflows, agents, instructions
|
||||
├── .vscode/ # VS Code settings and tasks
|
||||
├── backend/ # Go backend source
|
||||
├── configs/ # Runtime configurations
|
||||
├── docs/ # Documentation
|
||||
│ ├── implementation/ # Implementation/feature docs archive
|
||||
│ ├── plans/ # Planning documents
|
||||
│ └── ... # User-facing documentation
|
||||
├── frontend/ # React frontend source
|
||||
├── scripts/ # Build/test scripts
|
||||
├── test-results/ # Test outputs (gitignored)
|
||||
├── tools/ # Development tools
|
||||
└── [standard files] # README, LICENSE, Makefile, etc.
|
||||
```
|
||||
|
||||
## Enforcement
|
||||
|
||||
This structure is enforced by:
|
||||
|
||||
- `.gitignore` patterns preventing commits of artifacts at root
|
||||
- Code review guidelines
|
||||
- These instructions for AI assistants
|
||||
|
||||
When reviewing PRs or generating code, ensure new files follow these placement rules.
|
||||
@@ -18,4 +18,4 @@ REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
|
||||
cd "$REPO_ROOT"
|
||||
|
||||
# Start development environment with Docker Compose
|
||||
exec docker compose -f docker-compose.dev.yml up -d
|
||||
exec docker compose -f .docker/compose/docker-compose.dev.yml up -d
|
||||
|
||||
@@ -41,13 +41,13 @@ metadata:
|
||||
|
||||
## Overview
|
||||
|
||||
Starts the Charon development Docker Compose environment in detached mode. This brings up all required services including the application, database, CrowdSec, and any other dependencies defined in `docker-compose.dev.yml`.
|
||||
Starts the Charon development Docker Compose environment in detached mode. This brings up all required services including the application, database, CrowdSec, and any other dependencies defined in `.docker/compose/docker-compose.dev.yml`.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Docker Engine installed and running
|
||||
- Docker Compose V2 installed
|
||||
- `docker-compose.dev.yml` file in repository root
|
||||
- `.docker/compose/docker-compose.dev.yml` file in repository
|
||||
- Network access (for pulling images)
|
||||
- Sufficient system resources (CPU, memory, disk)
|
||||
|
||||
@@ -71,13 +71,13 @@ Use the task: **Docker: Start Dev Environment**
|
||||
|
||||
## Parameters
|
||||
|
||||
This skill accepts no parameters. Services are configured in `docker-compose.dev.yml`.
|
||||
This skill accepts no parameters. Services are configured in `.docker/compose/docker-compose.dev.yml`.
|
||||
|
||||
## Environment Variables
|
||||
|
||||
This skill uses environment variables defined in:
|
||||
- `.env` (if present)
|
||||
- `docker-compose.dev.yml` environment section
|
||||
- `.docker/compose/docker-compose.dev.yml` environment section
|
||||
- Shell environment
|
||||
|
||||
## Outputs
|
||||
@@ -99,7 +99,7 @@ This skill uses environment variables defined in:
|
||||
|
||||
## What Gets Started
|
||||
|
||||
Services defined in `docker-compose.dev.yml`:
|
||||
Services defined in `.docker/compose/docker-compose.dev.yml`:
|
||||
1. **charon-app**: Main application container
|
||||
2. **charon-db**: SQLite or PostgreSQL database
|
||||
3. **crowdsec**: Security bouncer
|
||||
@@ -123,7 +123,7 @@ Docker Compose respects `depends_on` directives:
|
||||
.github/skills/docker-start-dev-scripts/run.sh
|
||||
|
||||
# Verify services are running
|
||||
docker compose -f docker-compose.dev.yml ps
|
||||
docker compose -f .docker/compose/docker-compose.dev.yml ps
|
||||
```
|
||||
|
||||
### Example 2: Start and View Logs
|
||||
@@ -133,7 +133,7 @@ docker compose -f docker-compose.dev.yml ps
|
||||
.github/skills/docker-start-dev-scripts/run.sh
|
||||
|
||||
# Follow logs from all services
|
||||
docker compose -f docker-compose.dev.yml logs -f
|
||||
docker compose -f .docker/compose/docker-compose.dev.yml logs -f
|
||||
```
|
||||
|
||||
### Example 3: Start and Test Application
|
||||
@@ -155,18 +155,18 @@ After starting, verify services are healthy:
|
||||
|
||||
```bash
|
||||
# Check service status
|
||||
docker compose -f docker-compose.dev.yml ps
|
||||
docker compose -f .docker/compose/docker-compose.dev.yml ps
|
||||
|
||||
# Check specific service logs
|
||||
docker compose -f docker-compose.dev.yml logs app
|
||||
docker compose -f .docker/compose/docker-compose.dev.yml logs app
|
||||
|
||||
# Execute command in running container
|
||||
docker compose -f docker-compose.dev.yml exec app /bin/sh
|
||||
docker compose -f .docker/compose/docker-compose.dev.yml exec app /bin/sh
|
||||
```
|
||||
|
||||
## Port Mappings
|
||||
|
||||
Default development ports (check `docker-compose.dev.yml`):
|
||||
Default development ports (check `.docker/compose/docker-compose.dev.yml`):
|
||||
- **8080**: Application HTTP
|
||||
- **8443**: Application HTTPS (if configured)
|
||||
- **9000**: Admin panel (if configured)
|
||||
@@ -213,7 +213,7 @@ After starting, verify:
|
||||
|
||||
1. **All Services Running**:
|
||||
```bash
|
||||
docker compose -f docker-compose.dev.yml ps
|
||||
docker compose -f .docker/compose/docker-compose.dev.yml ps
|
||||
```
|
||||
|
||||
2. **Application Accessible**:
|
||||
@@ -223,7 +223,7 @@ After starting, verify:
|
||||
|
||||
3. **No Error Logs**:
|
||||
```bash
|
||||
docker compose -f docker-compose.dev.yml logs --tail=50
|
||||
docker compose -f .docker/compose/docker-compose.dev.yml logs --tail=50
|
||||
```
|
||||
|
||||
## Related Skills
|
||||
@@ -246,9 +246,9 @@ After starting, verify:
|
||||
### Services Won't Start
|
||||
|
||||
1. Check Docker daemon: `docker info`
|
||||
2. Validate compose file: `docker compose -f docker-compose.dev.yml config`
|
||||
2. Validate compose file: `docker compose -f .docker/compose/docker-compose.dev.yml config`
|
||||
3. Check available resources: `docker stats`
|
||||
4. Review logs: `docker compose -f docker-compose.dev.yml logs`
|
||||
4. Review logs: `docker compose -f .docker/compose/docker-compose.dev.yml logs`
|
||||
|
||||
### Slow Startup
|
||||
|
||||
@@ -266,4 +266,4 @@ After starting, verify:
|
||||
|
||||
**Last Updated**: 2025-12-20
|
||||
**Maintained by**: Charon Project
|
||||
**Compose File**: `docker-compose.dev.yml`
|
||||
**Compose File**: `.docker/compose/docker-compose.dev.yml`
|
||||
|
||||
@@ -18,4 +18,4 @@ REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
|
||||
cd "$REPO_ROOT"
|
||||
|
||||
# Stop development environment with Docker Compose
|
||||
exec docker compose -f docker-compose.dev.yml down
|
||||
exec docker compose -f .docker/compose/docker-compose.dev.yml down
|
||||
|
||||
@@ -49,7 +49,7 @@ Stops and removes all containers defined in the Charon development Docker Compos
|
||||
- Docker Engine installed and running
|
||||
- Docker Compose V2 installed
|
||||
- Development environment previously started
|
||||
- `docker-compose.dev.yml` file in repository root
|
||||
- `.docker/compose/docker-compose.dev.yml` file in repository
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -96,7 +96,7 @@ This skill requires no environment variables.
|
||||
|
||||
## What Gets Stopped
|
||||
|
||||
Services defined in `docker-compose.dev.yml`:
|
||||
Services defined in `.docker/compose/docker-compose.dev.yml`:
|
||||
1. **Application Containers**: Charon main app
|
||||
2. **Database Containers**: SQLite/PostgreSQL services
|
||||
3. **Security Services**: CrowdSec bouncer
|
||||
@@ -110,7 +110,7 @@ The `down` command preserves:
|
||||
- **Images**: Docker images remain cached
|
||||
- **Configs**: Configuration files unchanged
|
||||
|
||||
To remove volumes, use `docker compose -f docker-compose.dev.yml down -v`
|
||||
To remove volumes, use `docker compose -f .docker/compose/docker-compose.dev.yml down -v`
|
||||
|
||||
## Shutdown Order
|
||||
|
||||
@@ -129,14 +129,14 @@ Docker Compose stops services in reverse dependency order:
|
||||
.github/skills/docker-stop-dev-scripts/run.sh
|
||||
|
||||
# Verify services are stopped
|
||||
docker compose -f docker-compose.dev.yml ps
|
||||
docker compose -f .docker/compose/docker-compose.dev.yml ps
|
||||
```
|
||||
|
||||
### Example 2: Stop and Remove Volumes
|
||||
|
||||
```bash
|
||||
# Stop services and remove data volumes
|
||||
docker compose -f docker-compose.dev.yml down -v
|
||||
docker compose -f .docker/compose/docker-compose.dev.yml down -v
|
||||
```
|
||||
|
||||
### Example 3: Stop and Verify Cleanup
|
||||
@@ -269,4 +269,4 @@ docker rmi $(docker images -q "*charon*")
|
||||
|
||||
**Last Updated**: 2025-12-20
|
||||
**Maintained by**: Charon Project
|
||||
**Compose File**: `docker-compose.dev.yml`
|
||||
**Compose File**: `.docker/compose/docker-compose.dev.yml`
|
||||
|
||||
Reference in New Issue
Block a user