Initial commit: Complete NodeJS-native setup
- Migrated from Python pre-commit to NodeJS-native solution - Reorganized documentation structure - Set up Husky + lint-staged for efficient pre-commit hooks - Fixed Dockerfile healthcheck issue - Added comprehensive documentation index
This commit is contained in:
William Valentin
119
docs/migration/BUILDX_MIGRATION.md
Normal file
119
docs/migration/BUILDX_MIGRATION.md
Normal file
@@ -0,0 +1,119 @@
|
||||
# Docker Buildx Migration Complete ✅
|
||||
|
||||
Your project has been successfully migrated to use Docker Buildx for multi-platform container builds!
|
||||
|
||||
## What's New
|
||||
|
||||
### 🚀 Multi-Platform Support
|
||||
|
||||
- **AMD64 (x86_64)**: Traditional Intel/AMD processors
|
||||
- **ARM64 (aarch64)**: Apple Silicon, AWS Graviton, Raspberry Pi 4+
|
||||
|
||||
### 🛠️ New Tools & Scripts
|
||||
|
||||
#### **buildx-helper.sh** - Comprehensive buildx management
|
||||
|
||||
```bash
|
||||
# Setup buildx builder (one-time setup)
|
||||
./scripts/buildx-helper.sh setup
|
||||
|
||||
# Build for local platform only (faster development)
|
||||
./scripts/buildx-helper.sh build-local
|
||||
|
||||
# Build for multiple platforms
|
||||
./scripts/buildx-helper.sh build-multi
|
||||
|
||||
# Build and push to registry
|
||||
./scripts/buildx-helper.sh push docker.io/username latest
|
||||
|
||||
# Build using Docker Bake (advanced)
|
||||
./scripts/buildx-helper.sh bake
|
||||
|
||||
# Inspect builder capabilities
|
||||
./scripts/buildx-helper.sh inspect
|
||||
|
||||
# Cleanup builder
|
||||
./scripts/buildx-helper.sh cleanup
|
||||
```
|
||||
|
||||
#### **Package.json Scripts**
|
||||
|
||||
```bash
|
||||
# Quick access via npm/bun scripts
|
||||
bun run docker:setup # Setup buildx
|
||||
bun run docker:build # Multi-platform build
|
||||
bun run docker:build-local # Local platform only
|
||||
bun run docker:bake # Advanced bake build
|
||||
bun run docker:inspect # Inspect builder
|
||||
bun run docker:cleanup # Cleanup
|
||||
```
|
||||
|
||||
### 📁 New Files Added
|
||||
|
||||
1. **`docker/docker-bake.hcl`** - Advanced buildx configuration
|
||||
2. **`scripts/buildx-helper.sh`** - Buildx management script
|
||||
3. **`.github/workflows/build-deploy.yml`** - CI/CD with buildx
|
||||
|
||||
### 🔧 Updated Files
|
||||
|
||||
1. **`docker/Dockerfile`** - Added NODE_ENV build arg
|
||||
2. **`docker/docker-compose.yaml`** - Added multi-platform support
|
||||
3. **`scripts/setup.sh`** - Updated to use buildx
|
||||
4. **`scripts/validate-deployment.sh`** - Updated to use buildx
|
||||
5. **`scripts/deploy.sh`** - Updated to use buildx
|
||||
6. **`docker/README.md`** - Added buildx documentation
|
||||
7. **`package.json`** - Added docker scripts
|
||||
|
||||
## Benefits
|
||||
|
||||
### 🎯 **Better Performance**
|
||||
|
||||
- Enhanced caching with BuildKit
|
||||
- Parallel multi-platform builds
|
||||
- Faster incremental builds
|
||||
|
||||
### 🌍 **Cross-Platform Compatibility**
|
||||
|
||||
- Deploy on ARM-based servers (AWS Graviton, Apple Silicon)
|
||||
- Support for various architectures out of the box
|
||||
- Future-proof for emerging platforms
|
||||
|
||||
### 🔒 **Enhanced Security**
|
||||
|
||||
- Supply chain attestations (SBOM, provenance)
|
||||
- Secure multi-stage builds
|
||||
- Container image signing support
|
||||
|
||||
### 🔄 **CI/CD Ready**
|
||||
|
||||
- GitHub Actions workflow included
|
||||
- Registry caching optimized
|
||||
- Automated multi-platform pushes
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Test the setup**:
|
||||
|
||||
```bash
|
||||
bun run docker:setup
|
||||
bun run docker:build-local
|
||||
```
|
||||
|
||||
2. **Configure registry** (optional):
|
||||
|
||||
```bash
|
||||
./scripts/buildx-helper.sh push ghcr.io/yourusername latest
|
||||
```
|
||||
|
||||
3. **Enable GitHub Actions** (optional):
|
||||
- Push to GitHub to trigger the workflow
|
||||
- Configure registry secrets if needed
|
||||
|
||||
## Migration Notes
|
||||
|
||||
- ✅ Backwards compatible with existing Docker commands
|
||||
- ✅ Docker Compose still works as before
|
||||
- ✅ All existing scripts updated to use buildx
|
||||
- ✅ No breaking changes to development workflow
|
||||
|
||||
Your project now supports cutting-edge multi-platform container builds! 🎉
|
||||
117
docs/migration/NODEJS_PRECOMMIT_MIGRATION.md
Normal file
117
docs/migration/NODEJS_PRECOMMIT_MIGRATION.md
Normal file
@@ -0,0 +1,117 @@
|
||||
# NodeJS-Native Pre-commit Setup Migration
|
||||
|
||||
## Overview
|
||||
|
||||
Successfully migrated from Python's `pre-commit` framework to a 100% NodeJS-native solution using Husky and lint-staged.
|
||||
|
||||
## What Was Removed
|
||||
|
||||
- `.pre-commit-config.yaml` - Python pre-commit configuration
|
||||
- `.secrets.baseline` - Python detect-secrets baseline
|
||||
- Python `pre-commit` dependency requirement
|
||||
- Python `detect-secrets` dependency requirement
|
||||
|
||||
## What Was Added
|
||||
|
||||
### Core Tools
|
||||
|
||||
- **Husky v9** - Modern Git hooks manager
|
||||
- **lint-staged** - Run tools on staged files only (performance optimization)
|
||||
|
||||
### NodeJS Alternatives for Previous Python Tools
|
||||
|
||||
| Python Tool | NodeJS Alternative | Purpose |
|
||||
| ------------------ | --------------------------- | -------------------------------------- |
|
||||
| `pre-commit-hooks` | Built into Husky hook | File checks, trailing whitespace, etc. |
|
||||
| `mirrors-prettier` | `prettier` (direct) | Code formatting |
|
||||
| `eslint` (local) | `eslint` (direct) | JavaScript/TypeScript linting |
|
||||
| `tsc` (local) | `typescript` (direct) | Type checking |
|
||||
| `hadolint` | `dockerfilelint` | Dockerfile linting |
|
||||
| `shellcheck-py` | Custom shell checks in hook | Shell script validation |
|
||||
| `markdownlint-cli` | `markdownlint-cli2` | Markdown linting |
|
||||
| `detect-secrets` | `@secretlint/node` | Secret detection |
|
||||
|
||||
## New Package.json Scripts
|
||||
|
||||
```json
|
||||
{
|
||||
"lint:markdown": "markdownlint-cli2 \"**/*.md\"",
|
||||
"lint:markdown:fix": "markdownlint-cli2 --fix \"**/*.md\"",
|
||||
"lint:docker": "dockerfilelint docker/Dockerfile",
|
||||
"check:secrets": "secretlint \"**/*\"",
|
||||
"check:editorconfig": "eclint check .",
|
||||
"fix:editorconfig": "eclint fix ."
|
||||
}
|
||||
```
|
||||
|
||||
## Enhanced lint-staged Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"lint-staged": {
|
||||
"*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"],
|
||||
"*.{json,yaml,yml,md,css,scss,html}": ["prettier --write"],
|
||||
"*.md": ["markdownlint-cli2 --fix"],
|
||||
"docker/Dockerfile": ["dockerfilelint"],
|
||||
"*": ["eclint fix"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Husky Hooks
|
||||
|
||||
### `.husky/pre-commit`
|
||||
|
||||
- Runs lint-staged for efficient file-specific checks
|
||||
- TypeScript type checking
|
||||
- Large file detection (>500KB)
|
||||
- Merge conflict marker detection
|
||||
- Basic private key detection
|
||||
|
||||
### `.husky/commit-msg`
|
||||
|
||||
- Basic commit message validation
|
||||
|
||||
## Key Benefits
|
||||
|
||||
1. **No Python Dependencies** - Pure NodeJS ecosystem
|
||||
2. **Better Performance** - lint-staged only processes changed files
|
||||
3. **Simpler Setup** - No Python virtual environment needed
|
||||
4. **Consistent Toolchain** - Everything uses npm/bun
|
||||
5. **Modern Tooling** - Latest versions of all tools
|
||||
6. **Easier CI/CD** - Same tools in development and CI
|
||||
|
||||
## Usage
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
|
||||
./scripts/setup-pre-commit.sh
|
||||
```
|
||||
|
||||
### Manual Commands
|
||||
|
||||
```bash
|
||||
bun run format # Format all files
|
||||
bun run lint:fix # Fix linting issues
|
||||
bun run lint:markdown:fix # Fix markdown issues
|
||||
|
||||
bun run check:secrets # Check for secrets
|
||||
bun run type-check # TypeScript validation
|
||||
```
|
||||
|
||||
### What Happens on Commit
|
||||
|
||||
1. **lint-staged** processes only changed files:
|
||||
- ESLint auto-fix + Prettier for JS/TS files
|
||||
- Prettier for JSON/YAML/MD/CSS files
|
||||
- Markdownlint for Markdown files
|
||||
- Dockerfilelint for Dockerfile
|
||||
- EditorConfig fixes for all files
|
||||
2. **TypeScript** type checking on entire project
|
||||
3. **Security checks** for large files, merge conflicts, private keys
|
||||
|
||||
## Migration Complete ✅
|
||||
|
||||
The project now uses a modern, efficient, NodeJS-native pre-commit setup that provides the same (and better) functionality as the previous Python-based solution.
|
||||
Reference in New Issue
Block a user