fix(docs): fix file endings and formatting in documentation
This commit is contained in:
Jesús Pérez
parent
35acc1987e
commit
a17595aaaf
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@ -1 +1,98 @@
|
||||
# TypeDialog + Nickel Configuration Scripts\n\nPhase 8 Nushell automation scripts for interactive configuration workflow, config generation, validation, and deployment.\n\n## Quick Start\n\n```\n# 1. Interactive Configuration (TypeDialog)\nnu scripts/configure.nu orchestrator solo\n\n# 2. Generate TOML configs\nnu scripts/generate-configs.nu orchestrator solo\n\n# 3. Validate configuration\nnu scripts/validate-config.nu provisioning/.typedialog/provisioning/platform/values/orchestrator.solo.ncl\n\n# 4. Render Docker Compose\nnu scripts/render-docker-compose.nu solo\n\n# 5. Full deployment workflow\nnu scripts/install-services.nu orchestrator solo --docker\n```\n\n## Scripts Overview\n\n### Shared Helpers\n- **ansi.nu** - ANSI color and emoji output formatting\n- **paths.nu** - Path validation and directory structure helpers \n- **external.nu** - Safe external command execution with error handling\n\n### Core Configuration Scripts\n- **configure.nu** - Interactive TypeDialog configuration wizard\n- **generate-configs.nu** - Export Nickel configs to TOML\n- **validate-config.nu** - Validate Nickel configuration\n\n### Rendering Scripts\n- **render-docker-compose.nu** - Render Docker Compose from Nickel templates\n- **render-kubernetes.nu** - Render Kubernetes manifests from Nickel templates\n\n### Deployment & Monitoring Scripts\n- **install-services.nu** - Full deployment orchestration\n- **detect-services.nu** - Auto-detect running services\n\n## Supported Services\n- orchestrator (port 9090)\n- control-center (port 8080)\n- mcp-server (port 8888)\n- installer (port 8000)\n\n## Supported Deployment Modes\n- solo (2 CPU, 4GB RAM)\n- multiuser (4 CPU, 8GB RAM)\n- cicd (8 CPU, 16GB RAM)\n- enterprise (16+ CPU, 32+ GB RAM)\n\n## Nushell Compliance\nAll scripts follow Nushell 0.109.0+ guidelines with proper type signatures, error handling, and no try-catch blocks.\n\n## Examples\n\n### Single Service Configuration\n```\nnu scripts/configure.nu orchestrator solo --backend web\nnu scripts/validate-config.nu provisioning/.typedialog/provisioning/platform/values/orchestrator.solo.ncl\nnu scripts/generate-configs.nu orchestrator solo\ncargo run -p orchestrator -- --config provisioning/platform/config/orchestrator.solo.toml\n```\n\n### Docker Compose Deployment\n```\nnu scripts/generate-configs.nu orchestrator multiuser\nnu scripts/render-docker-compose.nu multiuser\ndocker-compose -f provisioning/platform/infrastructure/docker/docker-compose.multiuser.yml up -d\n```\n\n### Kubernetes Deployment\n```\nnu scripts/generate-configs.nu orchestrator enterprise\nnu scripts/render-kubernetes.nu enterprise --namespace production\nnu scripts/install-services.nu all enterprise --kubernetes --namespace production\n```\n\n## Phase 8 Status\n\n✅ Phase 8.A: Shared helper modules\n✅ Phase 8.B: Core configuration scripts \n✅ Phase 8.C: Rendering scripts\n✅ Phase 8.D: Deployment orchestration\n✅ Phase 8.E: Testing and documentation\n\n## Requirements\n\n- Nushell 0.109.1+\n- Nickel 1.15.1+\n- TypeDialog CLI\n- yq v4.50.1+\n- Docker (optional)\n- kubectl (optional)
|
||||
# TypeDialog + Nickel Configuration Scripts
|
||||
|
||||
Phase 8 Nushell automation scripts for interactive configuration workflow, config generation, validation, and deployment.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```toml
|
||||
# 1. Interactive Configuration (TypeDialog)
|
||||
nu scripts/configure.nu orchestrator solo
|
||||
|
||||
# 2. Generate TOML configs
|
||||
nu scripts/generate-configs.nu orchestrator solo
|
||||
|
||||
# 3. Validate configuration
|
||||
nu scripts/validate-config.nu provisioning/.typedialog/provisioning/platform/values/orchestrator.solo.ncl
|
||||
|
||||
# 4. Render Docker Compose
|
||||
nu scripts/render-docker-compose.nu solo
|
||||
|
||||
# 5. Full deployment workflow
|
||||
nu scripts/install-services.nu orchestrator solo --docker
|
||||
```
|
||||
|
||||
## Scripts Overview
|
||||
|
||||
### Shared Helpers
|
||||
- **ansi.nu** - ANSI color and emoji output formatting
|
||||
- **paths.nu** - Path validation and directory structure helpers
|
||||
- **external.nu** - Safe external command execution with error handling
|
||||
|
||||
### Core Configuration Scripts
|
||||
- **configure.nu** - Interactive TypeDialog configuration wizard
|
||||
- **generate-configs.nu** - Export Nickel configs to TOML
|
||||
- **validate-config.nu** - Validate Nickel configuration
|
||||
|
||||
### Rendering Scripts
|
||||
- **render-docker-compose.nu** - Render Docker Compose from Nickel templates
|
||||
- **render-kubernetes.nu** - Render Kubernetes manifests from Nickel templates
|
||||
|
||||
### Deployment & Monitoring Scripts
|
||||
- **install-services.nu** - Full deployment orchestration
|
||||
- **detect-services.nu** - Auto-detect running services
|
||||
|
||||
## Supported Services
|
||||
- orchestrator (port 9090)
|
||||
- control-center (port 8080)
|
||||
- mcp-server (port 8888)
|
||||
- installer (port 8000)
|
||||
|
||||
## Supported Deployment Modes
|
||||
- solo (2 CPU, 4GB RAM)
|
||||
- multiuser (4 CPU, 8GB RAM)
|
||||
- cicd (8 CPU, 16GB RAM)
|
||||
- enterprise (16+ CPU, 32+ GB RAM)
|
||||
|
||||
## Nushell Compliance
|
||||
All scripts follow Nushell 0.109.0+ guidelines with proper type signatures, error handling, and no try-catch blocks.
|
||||
|
||||
## Examples
|
||||
|
||||
### Single Service Configuration
|
||||
```toml
|
||||
nu scripts/configure.nu orchestrator solo --backend web
|
||||
nu scripts/validate-config.nu provisioning/.typedialog/provisioning/platform/values/orchestrator.solo.ncl
|
||||
nu scripts/generate-configs.nu orchestrator solo
|
||||
cargo run -p orchestrator -- --config provisioning/platform/config/orchestrator.solo.toml
|
||||
```
|
||||
|
||||
### Docker Compose Deployment
|
||||
```toml
|
||||
nu scripts/generate-configs.nu orchestrator multiuser
|
||||
nu scripts/render-docker-compose.nu multiuser
|
||||
docker-compose -f provisioning/platform/infrastructure/docker/docker-compose.multiuser.yml up -d
|
||||
```
|
||||
|
||||
### Kubernetes Deployment
|
||||
```yaml
|
||||
nu scripts/generate-configs.nu orchestrator enterprise
|
||||
nu scripts/render-kubernetes.nu enterprise --namespace production
|
||||
nu scripts/install-services.nu all enterprise --kubernetes --namespace production
|
||||
```
|
||||
|
||||
## Phase 8 Status
|
||||
|
||||
✅ Phase 8.A: Shared helper modules
|
||||
✅ Phase 8.B: Core configuration scripts
|
||||
✅ Phase 8.C: Rendering scripts
|
||||
✅ Phase 8.D: Deployment orchestration
|
||||
✅ Phase 8.E: Testing and documentation
|
||||
|
||||
## Requirements
|
||||
|
||||
- Nushell 0.109.1+
|
||||
- Nickel 1.15.1+
|
||||
- TypeDialog CLI
|
||||
- yq v4.50.1+
|
||||
- Docker (optional)
|
||||
- kubectl (optional)
|
||||
File diff suppressed because one or more lines are too long
132
CHANGELOG.md
132
CHANGELOG.md
File diff suppressed because one or more lines are too long
@ -1 +1,107 @@
|
||||
# Code of Conduct\n\n## Our Pledge\n\nWe, as members, contributors, and leaders, pledge to make participation in our project and community a harassment-free experience for everyone, regardless of:\n\n- Age\n- Body size\n- Visible or invisible disability\n- Ethnicity\n- Sex characteristics\n- Gender identity and expression\n- Level of experience\n- Education\n- Socioeconomic status\n- Nationality\n- Personal appearance\n- Race\n- Caste\n- Color\n- Religion\n- Sexual identity and orientation\n\nWe pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.\n\n## Our Standards\n\nExamples of behavior that contributes to a positive environment for our community include:\n\n- Demonstrating empathy and kindness toward other people\n- Being respectful of differing opinions, viewpoints, and experiences\n- Giving and gracefully accepting constructive feedback\n- Accepting responsibility and apologizing to those affected by mistakes\n- Focusing on what is best not just for us as individuals, but for the overall community\n\nExamples of unacceptable behavior include:\n\n- The use of sexualized language or imagery\n- Trolling, insulting, or derogatory comments\n- Personal or political attacks\n- Public or private harassment\n- Publishing others' private information (doxing)\n- Other conduct which could reasonably be considered inappropriate in a professional setting\n\n## Enforcement Responsibilities\n\nProject maintainers are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate corrective action in response to unacceptable behavior.\n\nMaintainers have the right and responsibility to:\n\n- Remove, edit, or reject comments, commits, code, and other contributions\n- Ban contributors for behavior they deem inappropriate, threatening, or harmful\n\n## Scope\n\nThis Code of Conduct applies to:\n\n- All community spaces (GitHub, forums, chat, events, etc.)\n- Official project channels and representations\n- Interactions between community members related to the project\n\n## Enforcement\n\nInstances of abusive, harassing, or otherwise unacceptable behavior may be reported to project maintainers:\n\n- Email: [project contact]\n- GitHub: Private security advisory\n- Issues: Report with `conduct` label (public discussions only)\n\nAll complaints will be reviewed and investigated promptly and fairly.\n\n### Enforcement Guidelines\n\n**1. Correction**\n\n- Community impact: Use of inappropriate language or unwelcoming behavior\n- Action: Private written warning with explanation and clarity on impact\n- Consequence: Warning and no further violations\n\n**2. Warning**\n\n- Community impact: Violation through single incident or series of actions\n- Action: Written warning with severity consequences for continued behavior\n- Consequence: Suspension from community interaction\n\n**3. Temporary Ban**\n\n- Community impact: Serious violation of standards\n- Action: Temporary ban from community interaction\n- Consequence: Revocation of ban after reflection period\n\n**4. Permanent Ban**\n\n- Community impact: Pattern of violating community standards\n- Action: Permanent ban from community interaction\n\n## Attribution\n\nThis Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.\n\nFor answers to common questions about this code of conduct, see the FAQ at <https://www.contributor-covenant.org/faq>.\n\n---\n\n**Thank you for being part of our community!**\n\nWe believe in creating a welcoming and inclusive space where everyone can contribute their best work. Together, we make this project better.
|
||||
# Code of Conduct
|
||||
|
||||
## Our Pledge
|
||||
|
||||
We, as members, contributors, and leaders, pledge to make participation in our project and community a harassment-free experience for everyone, regardless of:
|
||||
|
||||
- Age
|
||||
- Body size
|
||||
- Visible or invisible disability
|
||||
- Ethnicity
|
||||
- Sex characteristics
|
||||
- Gender identity and expression
|
||||
- Level of experience
|
||||
- Education
|
||||
- Socioeconomic status
|
||||
- Nationality
|
||||
- Personal appearance
|
||||
- Race
|
||||
- Caste
|
||||
- Color
|
||||
- Religion
|
||||
- Sexual identity and orientation
|
||||
|
||||
We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
|
||||
|
||||
## Our Standards
|
||||
|
||||
Examples of behavior that contributes to a positive environment for our community include:
|
||||
|
||||
- Demonstrating empathy and kindness toward other people
|
||||
- Being respectful of differing opinions, viewpoints, and experiences
|
||||
- Giving and gracefully accepting constructive feedback
|
||||
- Accepting responsibility and apologizing to those affected by mistakes
|
||||
- Focusing on what is best not just for us as individuals, but for the overall community
|
||||
|
||||
Examples of unacceptable behavior include:
|
||||
|
||||
- The use of sexualized language or imagery
|
||||
- Trolling, insulting, or derogatory comments
|
||||
- Personal or political attacks
|
||||
- Public or private harassment
|
||||
- Publishing others' private information (doxing)
|
||||
- Other conduct which could reasonably be considered inappropriate in a professional setting
|
||||
|
||||
## Enforcement Responsibilities
|
||||
|
||||
Project maintainers are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate corrective action in response to unacceptable behavior.
|
||||
|
||||
Maintainers have the right and responsibility to:
|
||||
|
||||
- Remove, edit, or reject comments, commits, code, and other contributions
|
||||
- Ban contributors for behavior they deem inappropriate, threatening, or harmful
|
||||
|
||||
## Scope
|
||||
|
||||
This Code of Conduct applies to:
|
||||
|
||||
- All community spaces (GitHub, forums, chat, events, etc.)
|
||||
- Official project channels and representations
|
||||
- Interactions between community members related to the project
|
||||
|
||||
## Enforcement
|
||||
|
||||
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to project maintainers:
|
||||
|
||||
- Email: [project contact]
|
||||
- GitHub: Private security advisory
|
||||
- Issues: Report with `conduct` label (public discussions only)
|
||||
|
||||
All complaints will be reviewed and investigated promptly and fairly.
|
||||
|
||||
### Enforcement Guidelines
|
||||
|
||||
**1. Correction**
|
||||
|
||||
- Community impact: Use of inappropriate language or unwelcoming behavior
|
||||
- Action: Private written warning with explanation and clarity on impact
|
||||
- Consequence: Warning and no further violations
|
||||
|
||||
**2. Warning**
|
||||
|
||||
- Community impact: Violation through single incident or series of actions
|
||||
- Action: Written warning with severity consequences for continued behavior
|
||||
- Consequence: Suspension from community interaction
|
||||
|
||||
**3. Temporary Ban**
|
||||
|
||||
- Community impact: Serious violation of standards
|
||||
- Action: Temporary ban from community interaction
|
||||
- Consequence: Revocation of ban after reflection period
|
||||
|
||||
**4. Permanent Ban**
|
||||
|
||||
- Community impact: Pattern of violating community standards
|
||||
- Action: Permanent ban from community interaction
|
||||
|
||||
## Attribution
|
||||
|
||||
This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.
|
||||
|
||||
For answers to common questions about this code of conduct, see the FAQ at <https://www.contributor-covenant.org/faq>.
|
||||
|
||||
---
|
||||
|
||||
**Thank you for being part of our community!**
|
||||
|
||||
We believe in creating a welcoming and inclusive space where everyone can contribute their best work. Together, we make this project better.
|
||||
|
||||
131
CONTRIBUTING.md
131
CONTRIBUTING.md
@ -1 +1,130 @@
|
||||
# Contributing to provisioning\n\nThank you for your interest in contributing! This document provides guidelines and instructions for contributing to this project.\n\n## Code of Conduct\n\nThis project adheres to a Code of Conduct. By participating, you are expected to uphold this code. Please see [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for details.\n\n## Getting Started\n\n### Prerequisites\n\n- Rust 1.70+ (if project uses Rust)\n- NuShell (if project uses Nushell scripts)\n- Git\n\n### Development Setup\n\n1. Fork the repository\n2. Clone your fork: `git clone https://repo.jesusperez.pro/jesus/provisioning`\n3. Add upstream: `git remote add upstream https://repo.jesusperez.pro/jesus/provisioning`\n4. Create a branch: `git checkout -b feature/your-feature`\n\n## Development Workflow\n\n### Before You Code\n\n- Check existing issues and pull requests to avoid duplication\n- Create an issue to discuss major changes before implementing\n- Assign yourself to let others know you're working on it\n\n### Code Standards\n\n#### Rust\n\n- Run `cargo fmt --all` before committing\n- All code must pass `cargo clippy -- -D warnings`\n- Write tests for new functionality\n- Maintain 100% documentation coverage for public APIs\n\n#### Nushell\n\n- Validate scripts with `nu --ide-check 100 script.nu`\n- Follow consistent naming conventions\n- Use type hints where applicable\n\n#### Nickel\n\n- Type check schemas with `nickel typecheck`\n- Document schema fields with comments\n- Test schema validation\n\n### Commit Guidelines\n\n- Write clear, descriptive commit messages\n- Reference issues with `Fixes #123` or `Related to #123`\n- Keep commits focused on a single concern\n- Use imperative mood: "Add feature" not "Added feature"\n\n### Testing\n\nAll changes must include tests:\n\n```\n# Run all tests\ncargo test --workspace\n\n# Run with coverage\ncargo llvm-cov --all-features --lcov\n\n# Run locally before pushing\njust ci-full\n```\n\n### Pull Request Process\n\n1. Update documentation for any changed functionality\n2. Add tests for new code\n3. Ensure all CI checks pass\n4. Request review from maintainers\n5. Be responsive to feedback and iterate quickly\n\n## Review Process\n\n- Maintainers will review your PR within 3-5 business days\n- Feedback is constructive and meant to improve the code\n- All discussions should be respectful and professional\n- Once approved, maintainers will merge the PR\n\n## Reporting Bugs\n\nFound a bug? Please file an issue with:\n\n- **Title**: Clear, descriptive title\n- **Description**: What happened and what you expected\n- **Steps to reproduce**: Minimal reproducible example\n- **Environment**: OS, Rust version, etc.\n- **Screenshots**: If applicable\n\n## Suggesting Enhancements\n\nHave an idea? Please file an issue with:\n\n- **Title**: Clear feature title\n- **Description**: What, why, and how\n- **Use cases**: Real-world scenarios where this would help\n- **Alternative approaches**: If you've considered any\n\n## Documentation\n\n- Keep README.md up to date\n- Document public APIs with rustdoc comments\n- Add examples for non-obvious functionality\n- Update CHANGELOG.md with your changes\n\n## Release Process\n\nMaintainers handle releases following semantic versioning:\n\n- MAJOR: Breaking changes\n- MINOR: New features (backward compatible)\n- PATCH: Bug fixes\n\n## Questions?\n\n- Check existing documentation and issues\n- Ask in discussions or open an issue\n- Join our community channels\n\nThank you for contributing!
|
||||
# Contributing to provisioning
|
||||
|
||||
Thank you for your interest in contributing! This document provides guidelines and instructions for contributing to this project.
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
This project adheres to a Code of Conduct. By participating, you are expected to uphold this code. Please see [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for details.
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Rust 1.70+ (if project uses Rust)
|
||||
- NuShell (if project uses Nushell scripts)
|
||||
- Git
|
||||
|
||||
### Development Setup
|
||||
|
||||
1. Fork the repository
|
||||
2. Clone your fork: `git clone https://repo.jesusperez.pro/jesus/provisioning`
|
||||
3. Add upstream: `git remote add upstream https://repo.jesusperez.pro/jesus/provisioning`
|
||||
4. Create a branch: `git checkout -b feature/your-feature`
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Before You Code
|
||||
|
||||
- Check existing issues and pull requests to avoid duplication
|
||||
- Create an issue to discuss major changes before implementing
|
||||
- Assign yourself to let others know you're working on it
|
||||
|
||||
### Code Standards
|
||||
|
||||
#### Rust
|
||||
|
||||
- Run `cargo fmt --all` before committing
|
||||
- All code must pass `cargo clippy -- -D warnings`
|
||||
- Write tests for new functionality
|
||||
- Maintain 100% documentation coverage for public APIs
|
||||
|
||||
#### Nushell
|
||||
|
||||
- Validate scripts with `nu --ide-check 100 script.nu`
|
||||
- Follow consistent naming conventions
|
||||
- Use type hints where applicable
|
||||
|
||||
#### Nickel
|
||||
|
||||
- Type check schemas with `nickel typecheck`
|
||||
- Document schema fields with comments
|
||||
- Test schema validation
|
||||
|
||||
### Commit Guidelines
|
||||
|
||||
- Write clear, descriptive commit messages
|
||||
- Reference issues with `Fixes #123` or `Related to #123`
|
||||
- Keep commits focused on a single concern
|
||||
- Use imperative mood: "Add feature" not "Added feature"
|
||||
|
||||
### Testing
|
||||
|
||||
All changes must include tests:
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
cargo test --workspace
|
||||
|
||||
# Run with coverage
|
||||
cargo llvm-cov --all-features --lcov
|
||||
|
||||
# Run locally before pushing
|
||||
just ci-full
|
||||
```
|
||||
|
||||
### Pull Request Process
|
||||
|
||||
1. Update documentation for any changed functionality
|
||||
2. Add tests for new code
|
||||
3. Ensure all CI checks pass
|
||||
4. Request review from maintainers
|
||||
5. Be responsive to feedback and iterate quickly
|
||||
|
||||
## Review Process
|
||||
|
||||
- Maintainers will review your PR within 3-5 business days
|
||||
- Feedback is constructive and meant to improve the code
|
||||
- All discussions should be respectful and professional
|
||||
- Once approved, maintainers will merge the PR
|
||||
|
||||
## Reporting Bugs
|
||||
|
||||
Found a bug? Please file an issue with:
|
||||
|
||||
- **Title**: Clear, descriptive title
|
||||
- **Description**: What happened and what you expected
|
||||
- **Steps to reproduce**: Minimal reproducible example
|
||||
- **Environment**: OS, Rust version, etc.
|
||||
- **Screenshots**: If applicable
|
||||
|
||||
## Suggesting Enhancements
|
||||
|
||||
Have an idea? Please file an issue with:
|
||||
|
||||
- **Title**: Clear feature title
|
||||
- **Description**: What, why, and how
|
||||
- **Use cases**: Real-world scenarios where this would help
|
||||
- **Alternative approaches**: If you've considered any
|
||||
|
||||
## Documentation
|
||||
|
||||
- Keep README.md up to date
|
||||
- Document public APIs with rustdoc comments
|
||||
- Add examples for non-obvious functionality
|
||||
- Update CHANGELOG.md with your changes
|
||||
|
||||
## Release Process
|
||||
|
||||
Maintainers handle releases following semantic versioning:
|
||||
|
||||
- MAJOR: Breaking changes
|
||||
- MINOR: New features (backward compatible)
|
||||
- PATCH: Bug fixes
|
||||
|
||||
## Questions?
|
||||
|
||||
- Check existing documentation and issues
|
||||
- Ask in discussions or open an issue
|
||||
- Join our community channels
|
||||
|
||||
Thank you for contributing!
|
||||
102
SECURITY.md
102
SECURITY.md
@ -1 +1,101 @@
|
||||
# Security Policy\n\n## Supported Versions\n\nThis project provides security updates for the following versions:\n\n| Version | Supported |\n|---------|-----------|\n| 1.x | ✅ Yes |\n| 0.x | ❌ No |\n\nOnly the latest major version receives security patches. Users are encouraged to upgrade to the latest version.\n\n## Reporting a Vulnerability\n\n**Do not open public GitHub issues for security vulnerabilities.**\n\nInstead, please report security issues to the maintainers privately:\n\n### Reporting Process\n\n1. Email security details to the maintainers (see project README for contact)\n2. Include:\n - Description of the vulnerability\n - Steps to reproduce (if possible)\n - Potential impact\n - Suggested fix (if you have one)\n\n3. Expect acknowledgment within 48 hours\n4. We will work on a fix and coordinate disclosure timing\n\n### Responsible Disclosure\n\n- Allow reasonable time for a fix before public disclosure\n- Work with us to understand and validate the issue\n- Maintain confidentiality until the fix is released\n\n## Security Best Practices\n\n### For Users\n\n- Keep dependencies up to date\n- Use the latest version of this project\n- Review security advisories regularly\n- Report vulnerabilities responsibly\n\n### For Contributors\n\n- Run `cargo audit` before submitting PRs\n- Use `cargo deny` to check license compliance\n- Follow secure coding practices\n- Don't hardcode secrets or credentials\n- Validate all external inputs\n\n## Dependency Security\n\nWe use automated tools to monitor dependencies:\n\n- **cargo-audit**: Scans for known security vulnerabilities\n- **cargo-deny**: Checks licenses and bans unsafe dependencies\n\nThese run in CI on every push and PR.\n\n## Code Review\n\nAll code changes go through review before merging:\n\n- At least one maintainer review required\n- Security implications considered\n- Tests required for all changes\n- CI checks must pass\n\n## Known Vulnerabilities\n\nWe maintain transparency about known issues:\n\n- Documented in GitHub security advisories\n- Announced in release notes\n- Tracked in issues with `security` label\n\n## Security Contact\n\nFor security inquiries, please contact:\n\n- Email: [project maintainers]\n- Issue: Open a private security advisory on GitHub\n\n## Changelog\n\nSecurity fixes are highlighted in CHANGELOG.md with [SECURITY] prefix.\n\n## Resources\n\n- [OWASP Top 10](https://owasp.org/www-project-top-ten/)\n- [CWE: Common Weakness Enumeration](https://cwe.mitre.org/)\n- [Rust Security](https://www.rust-lang.org/governance/security-disclosures)\n- [npm Security](https://docs.npmjs.com/about-npm/security)\n\n## Questions\n\nIf you have security questions (not vulnerabilities), open a discussion or issue with the `security` label.
|
||||
# Security Policy
|
||||
|
||||
## Supported Versions
|
||||
|
||||
This project provides security updates for the following versions:
|
||||
|
||||
| Version | Supported |
|
||||
|---------|-----------|
|
||||
| 1.x | ✅ Yes |
|
||||
| 0.x | ❌ No |
|
||||
|
||||
Only the latest major version receives security patches. Users are encouraged to upgrade to the latest version.
|
||||
|
||||
## Reporting a Vulnerability
|
||||
|
||||
**Do not open public GitHub issues for security vulnerabilities.**
|
||||
|
||||
Instead, please report security issues to the maintainers privately:
|
||||
|
||||
### Reporting Process
|
||||
|
||||
1. Email security details to the maintainers (see project README for contact)
|
||||
2. Include:
|
||||
- Description of the vulnerability
|
||||
- Steps to reproduce (if possible)
|
||||
- Potential impact
|
||||
- Suggested fix (if you have one)
|
||||
|
||||
3. Expect acknowledgment within 48 hours
|
||||
4. We will work on a fix and coordinate disclosure timing
|
||||
|
||||
### Responsible Disclosure
|
||||
|
||||
- Allow reasonable time for a fix before public disclosure
|
||||
- Work with us to understand and validate the issue
|
||||
- Maintain confidentiality until the fix is released
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
### For Users
|
||||
|
||||
- Keep dependencies up to date
|
||||
- Use the latest version of this project
|
||||
- Review security advisories regularly
|
||||
- Report vulnerabilities responsibly
|
||||
|
||||
### For Contributors
|
||||
|
||||
- Run `cargo audit` before submitting PRs
|
||||
- Use `cargo deny` to check license compliance
|
||||
- Follow secure coding practices
|
||||
- Don't hardcode secrets or credentials
|
||||
- Validate all external inputs
|
||||
|
||||
## Dependency Security
|
||||
|
||||
We use automated tools to monitor dependencies:
|
||||
|
||||
- **cargo-audit**: Scans for known security vulnerabilities
|
||||
- **cargo-deny**: Checks licenses and bans unsafe dependencies
|
||||
|
||||
These run in CI on every push and PR.
|
||||
|
||||
## Code Review
|
||||
|
||||
All code changes go through review before merging:
|
||||
|
||||
- At least one maintainer review required
|
||||
- Security implications considered
|
||||
- Tests required for all changes
|
||||
- CI checks must pass
|
||||
|
||||
## Known Vulnerabilities
|
||||
|
||||
We maintain transparency about known issues:
|
||||
|
||||
- Documented in GitHub security advisories
|
||||
- Announced in release notes
|
||||
- Tracked in issues with `security` label
|
||||
|
||||
## Security Contact
|
||||
|
||||
For security inquiries, please contact:
|
||||
|
||||
- Email: [project maintainers]
|
||||
- Issue: Open a private security advisory on GitHub
|
||||
|
||||
## Changelog
|
||||
|
||||
Security fixes are highlighted in CHANGELOG.md with [SECURITY] prefix.
|
||||
|
||||
## Resources
|
||||
|
||||
- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
|
||||
- [CWE: Common Weakness Enumeration](https://cwe.mitre.org/)
|
||||
- [Rust Security](https://www.rust-lang.org/governance/security-disclosures)
|
||||
- [npm Security](https://docs.npmjs.com/about-npm/security)
|
||||
|
||||
## Questions
|
||||
|
||||
If you have security questions (not vulnerabilities), open a discussion or issue with the `security` label.
|
||||
|
||||
File diff suppressed because one or more lines are too long
392
config/README.md
392
config/README.md
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@ -1 +1,170 @@
|
||||
# Constraints\n\nSingle source of truth for validation limits across all services.\n\n## Purpose\n\nThe `constraints.toml` file defines:\n- **Numeric ranges** (min/max values for ports, workers, timeouts, etc.)\n- **Uniqueness rules** (field constraints, array bounds)\n- **Validation bounds** (resource limits, timeout ranges)\n\nThese constraints are used by:\n1. **Validators** (`validators/*.ncl`) - Check that configuration values are within bounds\n2. **TypeDialog forms** (`forms/*.toml`) - Enable constraint interpolation for dynamic field validation\n3. **Nickel schemas** (`schemas/*.ncl`) - Define type contracts with bounds\n\n## File Structure\n\n```\nconstraints/\n└── constraints.toml # All validation constraints in TOML format\n```\n\n## Usage Pattern\n\n### 1. Define Constraint\n\n**constraints.toml**:\n\n```\n[orchestrator.queue.concurrent_tasks]\nmin = 1\nmax = 100\n```\n\n### 2. Reference in Validator\n\n**validators/orchestrator-validator.ncl**:\n\n```\nlet constraints = import "../constraints/constraints.toml" in\n\n{\n ValidConcurrentTasks = fun tasks =>\n if tasks < constraints.orchestrator.queue.concurrent_tasks.min then\n error "Tasks must be >= 1"\n else if tasks > constraints.orchestrator.queue.concurrent_tasks.max then\n error "Tasks must be <= 100"\n else\n tasks,\n}\n```\n\n### 3. Reference in Form\n\n**forms/fragments/orchestrator-queue-section.toml**:\n\n```\n[[elements]]\nname = "max_concurrent_tasks"\ntype = "number"\nmin = "${constraint.orchestrator.queue.concurrent_tasks.min}"\nmax = "${constraint.orchestrator.queue.concurrent_tasks.max}"\nhelp = "Max: ${constraint.orchestrator.queue.concurrent_tasks.max}"\nnickel_path = ["orchestrator", "queue", "max_concurrent_tasks"]\n```\n\n## Constraint Categories\n\n### Service-Specific Constraints\n\n- **Orchestrator** (`[orchestrator.*]`)\n - Worker count bounds\n - Queue concurrency limits\n - Task timeout ranges\n - Batch parallelism limits\n\n- **Control Center** (`[control_center.*]`)\n - JWT token expiration bounds\n - Rate limiting thresholds\n - RBAC policy limits\n\n- **MCP Server** (`[mcp_server.*]`)\n - Tool concurrency limits\n - Resource size bounds\n - Prompt template limits\n\n### Common Constraints\n\n- **Server** (`[common.server.*]`)\n - Port range (1024-65535)\n - Worker count\n - Connection limits\n\n- **Deployment** (`[deployment.{solo,multiuser,cicd,enterprise}.*]`)\n - CPU core bounds\n - Memory allocation bounds\n - Disk space requirements\n\n## Modifying Constraints\n\nWhen changing constraint bounds:\n\n1. **Update constraints.toml**\n2. **Update validators** that use the constraint\n3. **Update forms** that interpolate the constraint\n4. **Test validation** in forms and Nickel typecheck\n5. **Update documentation** of affected services\n\n### Example: Increase Max Queue Tasks\n\n**Before**:\n\n```\n[orchestrator.queue.concurrent_tasks]\nmin = 1\nmax = 100\n```\n\n**After**:\n\n```\n[orchestrator.queue.concurrent_tasks]\nmin = 1\nmax = 200 # Increased from 100\n```\n\n**Then**:\n1. Verify `validators/orchestrator-validator.ncl` still type-checks\n2. Form will automatically show new max (via constraint interpolation)\n3. Test with: `nu scripts/validate-config.nu values/orchestrator.*.ncl`\n\n## Constraint Interpolation in Forms\n\nTypeDialog supports dynamic constraint references via `${constraint.path.to.value}`:\n\n```\n# Static min/max\nmin = 1\nmax = 100\n\n# Dynamic from constraints.toml\nmin = "${constraint.orchestrator.queue.concurrent_tasks.min}"\nmax = "${constraint.orchestrator.queue.concurrent_tasks.max}"\n\n# Help text with dynamic reference\nhelp = "Value must be between ${constraint.orchestrator.queue.concurrent_tasks.min} and ${constraint.orchestrator.queue.concurrent_tasks.max}"\n```\n\n## Best Practices\n\n1. **Single source of truth** - Define constraint once in constraints.toml\n2. **Meaningful names** - Use clear path hierarchy (service.subsystem.property)\n3. **Document ranges** - Add comments explaining why min/max values exist\n4. **Validate propagation** - Ensure forms and validators reference the same constraint\n5. **Test edge cases** - Verify min/max values work in validators and forms\n\n## Files to Update When Modifying Constraints\n\nWhen you change `constraints/constraints.toml`:\n\n1. `validators/*.ncl` - Update validator bounds\n2. `forms/fragments/*.toml` - Update form field constraints\n3. `schemas/*.ncl` - Update type contracts if needed\n4. Documentation - Update service-specific constraint documentation\n\n---\n\n**Version**: 1.0.0\n**Last Updated**: 2025-01-05
|
||||
# Constraints
|
||||
|
||||
Single source of truth for validation limits across all services.
|
||||
|
||||
## Purpose
|
||||
|
||||
The `constraints.toml` file defines:
|
||||
- **Numeric ranges** (min/max values for ports, workers, timeouts, etc.)
|
||||
- **Uniqueness rules** (field constraints, array bounds)
|
||||
- **Validation bounds** (resource limits, timeout ranges)
|
||||
|
||||
These constraints are used by:
|
||||
1. **Validators** (`validators/*.ncl`) - Check that configuration values are within bounds
|
||||
2. **TypeDialog forms** (`forms/*.toml`) - Enable constraint interpolation for dynamic field validation
|
||||
3. **Nickel schemas** (`schemas/*.ncl`) - Define type contracts with bounds
|
||||
|
||||
## File Structure
|
||||
|
||||
```javascript
|
||||
constraints/
|
||||
└── constraints.toml # All validation constraints in TOML format
|
||||
```
|
||||
|
||||
## Usage Pattern
|
||||
|
||||
### 1. Define Constraint
|
||||
|
||||
**constraints.toml**:
|
||||
|
||||
```toml
|
||||
[orchestrator.queue.concurrent_tasks]
|
||||
min = 1
|
||||
max = 100
|
||||
```
|
||||
|
||||
### 2. Reference in Validator
|
||||
|
||||
**validators/orchestrator-validator.ncl**:
|
||||
|
||||
```javascript
|
||||
let constraints = import "../constraints/constraints.toml" in
|
||||
|
||||
{
|
||||
ValidConcurrentTasks = fun tasks =>
|
||||
if tasks < constraints.orchestrator.queue.concurrent_tasks.min then
|
||||
error "Tasks must be >= 1"
|
||||
else if tasks > constraints.orchestrator.queue.concurrent_tasks.max then
|
||||
error "Tasks must be <= 100"
|
||||
else
|
||||
tasks,
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Reference in Form
|
||||
|
||||
**forms/fragments/orchestrator-queue-section.toml**:
|
||||
|
||||
```toml
|
||||
[[elements]]
|
||||
name = "max_concurrent_tasks"
|
||||
type = "number"
|
||||
min = "${constraint.orchestrator.queue.concurrent_tasks.min}"
|
||||
max = "${constraint.orchestrator.queue.concurrent_tasks.max}"
|
||||
help = "Max: ${constraint.orchestrator.queue.concurrent_tasks.max}"
|
||||
nickel_path = ["orchestrator", "queue", "max_concurrent_tasks"]
|
||||
```
|
||||
|
||||
## Constraint Categories
|
||||
|
||||
### Service-Specific Constraints
|
||||
|
||||
- **Orchestrator** (`[orchestrator.*]`)
|
||||
- Worker count bounds
|
||||
- Queue concurrency limits
|
||||
- Task timeout ranges
|
||||
- Batch parallelism limits
|
||||
|
||||
- **Control Center** (`[control_center.*]`)
|
||||
- JWT token expiration bounds
|
||||
- Rate limiting thresholds
|
||||
- RBAC policy limits
|
||||
|
||||
- **MCP Server** (`[mcp_server.*]`)
|
||||
- Tool concurrency limits
|
||||
- Resource size bounds
|
||||
- Prompt template limits
|
||||
|
||||
### Common Constraints
|
||||
|
||||
- **Server** (`[common.server.*]`)
|
||||
- Port range (1024-65535)
|
||||
- Worker count
|
||||
- Connection limits
|
||||
|
||||
- **Deployment** (`[deployment.{solo,multiuser,cicd,enterprise}.*]`)
|
||||
- CPU core bounds
|
||||
- Memory allocation bounds
|
||||
- Disk space requirements
|
||||
|
||||
## Modifying Constraints
|
||||
|
||||
When changing constraint bounds:
|
||||
|
||||
1. **Update constraints.toml**
|
||||
2. **Update validators** that use the constraint
|
||||
3. **Update forms** that interpolate the constraint
|
||||
4. **Test validation** in forms and Nickel typecheck
|
||||
5. **Update documentation** of affected services
|
||||
|
||||
### Example: Increase Max Queue Tasks
|
||||
|
||||
**Before**:
|
||||
|
||||
```toml
|
||||
[orchestrator.queue.concurrent_tasks]
|
||||
min = 1
|
||||
max = 100
|
||||
```
|
||||
|
||||
**After**:
|
||||
|
||||
```toml
|
||||
[orchestrator.queue.concurrent_tasks]
|
||||
min = 1
|
||||
max = 200 # Increased from 100
|
||||
```
|
||||
|
||||
**Then**:
|
||||
1. Verify `validators/orchestrator-validator.ncl` still type-checks
|
||||
2. Form will automatically show new max (via constraint interpolation)
|
||||
3. Test with: `nu scripts/validate-config.nu values/orchestrator.*.ncl`
|
||||
|
||||
## Constraint Interpolation in Forms
|
||||
|
||||
TypeDialog supports dynamic constraint references via `${constraint.path.to.value}`:
|
||||
|
||||
```bash
|
||||
# Static min/max
|
||||
min = 1
|
||||
max = 100
|
||||
|
||||
# Dynamic from constraints.toml
|
||||
min = "${constraint.orchestrator.queue.concurrent_tasks.min}"
|
||||
max = "${constraint.orchestrator.queue.concurrent_tasks.max}"
|
||||
|
||||
# Help text with dynamic reference
|
||||
help = "Value must be between ${constraint.orchestrator.queue.concurrent_tasks.min} and ${constraint.orchestrator.queue.concurrent_tasks.max}"
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Single source of truth** - Define constraint once in constraints.toml
|
||||
2. **Meaningful names** - Use clear path hierarchy (service.subsystem.property)
|
||||
3. **Document ranges** - Add comments explaining why min/max values exist
|
||||
4. **Validate propagation** - Ensure forms and validators reference the same constraint
|
||||
5. **Test edge cases** - Verify min/max values work in validators and forms
|
||||
|
||||
## Files to Update When Modifying Constraints
|
||||
|
||||
When you change `constraints/constraints.toml`:
|
||||
|
||||
1. `validators/*.ncl` - Update validator bounds
|
||||
2. `forms/fragments/*.toml` - Update form field constraints
|
||||
3. `schemas/*.ncl` - Update type contracts if needed
|
||||
4. Documentation - Update service-specific constraint documentation
|
||||
|
||||
---
|
||||
|
||||
**Version**: 1.0.0
|
||||
**Last Updated**: 2025-01-05
|
||||
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@ -1 +1,162 @@
|
||||
# Full Infrastructure Template\n\nThis is a comprehensive infrastructure template with multiple server types and advanced configuration examples.\n\n## What's Included\n\n- **Web servers** - 2 frontend web servers\n- **Database server** - Backend database with private networking\n- **Kubernetes control plane** - Control plane node\n- **Kubernetes workers** - 2 worker nodes\n- **Advanced settings** - SSH config, monitoring, backup options\n- **Comprehensive examples** - Multiple server roles and configurations\n\n## Server Inventory\n\n| Hostname | Role | Network | Purpose |\n| ---------- | ------ | --------- | --------- |\n| web-01, web-02 | Web | Public + Private | Frontend application servers |\n| db-01 | Database | Private only | Backend database |\n| k8s-control-01 | K8s Control | Public + Private | Kubernetes control plane |\n| k8s-worker-01, k8s-worker-02 | K8s Worker | Public + Private | Kubernetes compute nodes |\n\n## Quick Start\n\n### 1. Load Required Modules\n\n```\ncd infra/<your-infra-name>\n\n# Load provider\nprovisioning mod load providers . upcloud\n\n# Load taskservs\nprovisioning mod load taskservs . kubernetes containerd cilium\n\n# Load cluster configurations (optional)\nprovisioning mod load clusters . buildkit\n```\n\n### 2. Customize Configuration\n\nEdit `servers.k`:\n\n**Provider-specific settings:**\n\n```\n# Uncomment and adjust for your provider\nplan = "2xCPU-4GB" # Server size\nstorage_size = 50 # Disk size in GB\n```\n\n**Task services:**\n\n```\n# Uncomment after loading modules\ntaskservs = [\n { name = "kubernetes", profile = "control-plane" }\n { name = "containerd", profile = "default" }\n { name = "cilium", profile = "default" }\n]\n```\n\n**Select servers to deploy:**\n\n```\n# Choose which server groups to deploy\nall_servers = web_servers + db_servers # Web + DB only\n# OR\nall_servers = k8s_control + k8s_workers # Kubernetes cluster only\n# OR\nall_servers = web_servers + db_servers + k8s_control + k8s_workers # Everything\n```\n\n### 3. Deploy\n\n```\n# Test configuration\nkcl run servers.k\n\n# Dry-run deployment (recommended)\nprovisioning s create --infra <name> --check\n\n# Deploy selected servers\nprovisioning s create --infra <name>\n\n# Or deploy specific server groups\nprovisioning s create --infra <name> --select web\n```\n\n## Architecture Examples\n\n### Web Application Stack\n\nDeploy web servers + database:\n\n```\nall_servers = web_servers + db_servers\n```\n\n### Kubernetes Cluster\n\nDeploy control plane + workers:\n\n```\nall_servers = k8s_control + k8s_workers\n```\n\n### Complete Infrastructure\n\nDeploy everything:\n\n```\nall_servers = web_servers + db_servers + k8s_control + k8s_workers\n```\n\n## Advanced Configuration\n\n### Network Segmentation\n\n- **Public servers**: web-01, web-02 (public + private networks)\n- **Private servers**: db-01 (private network only)\n- **Hybrid**: k8s nodes (public for API access, private for pod networking)\n\n### Monitoring\n\nMonitoring is pre-configured in settings:\n\n```\nmonitoring = {\n enabled = True\n metrics_port = 9100\n log_aggregation = True\n}\n```\n\n### SSH Configuration\n\nAdvanced SSH settings are included:\n\n```\nssh_config = {\n connect_timeout = 30\n retry_attempts = 3\n compression = True\n}\n```\n\n## Next Steps\n\n1. **Customize server specs** - Adjust CPU, memory, storage\n2. **Configure networking** - Set up firewall rules, load balancers\n3. **Add taskservs** - Uncomment and configure task services\n4. **Set up clusters** - Deploy Kubernetes or container clusters\n5. **Configure monitoring** - Set up metrics and logging\n6. **Implement backup** - Configure backup policies\n\n## Template Characteristics\n\n- **Complexity**: High\n- **Servers**: 6 examples (web, database, k8s)\n- **Pre-configured modules**: Examples for all major components\n- **Best for**: Production deployments, complex architectures, learning advanced patterns
|
||||
# Full Infrastructure Template
|
||||
|
||||
This is a comprehensive infrastructure template with multiple server types and advanced configuration examples.
|
||||
|
||||
## What's Included
|
||||
|
||||
- **Web servers** - 2 frontend web servers
|
||||
- **Database server** - Backend database with private networking
|
||||
- **Kubernetes control plane** - Control plane node
|
||||
- **Kubernetes workers** - 2 worker nodes
|
||||
- **Advanced settings** - SSH config, monitoring, backup options
|
||||
- **Comprehensive examples** - Multiple server roles and configurations
|
||||
|
||||
## Server Inventory
|
||||
|
||||
| Hostname | Role | Network | Purpose |
|
||||
| ---------- | ------ | --------- | --------- |
|
||||
| web-01, web-02 | Web | Public + Private | Frontend application servers |
|
||||
| db-01 | Database | Private only | Backend database |
|
||||
| k8s-control-01 | K8s Control | Public + Private | Kubernetes control plane |
|
||||
| k8s-worker-01, k8s-worker-02 | K8s Worker | Public + Private | Kubernetes compute nodes |
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Load Required Modules
|
||||
|
||||
```bash
|
||||
cd infra/<your-infra-name>
|
||||
|
||||
# Load provider
|
||||
provisioning mod load providers . upcloud
|
||||
|
||||
# Load taskservs
|
||||
provisioning mod load taskservs . kubernetes containerd cilium
|
||||
|
||||
# Load cluster configurations (optional)
|
||||
provisioning mod load clusters . buildkit
|
||||
```
|
||||
|
||||
### 2. Customize Configuration
|
||||
|
||||
Edit `servers.k`:
|
||||
|
||||
**Provider-specific settings:**
|
||||
|
||||
```toml
|
||||
# Uncomment and adjust for your provider
|
||||
plan = "2xCPU-4GB" # Server size
|
||||
storage_size = 50 # Disk size in GB
|
||||
```
|
||||
|
||||
**Task services:**
|
||||
|
||||
```bash
|
||||
# Uncomment after loading modules
|
||||
taskservs = [
|
||||
{ name = "kubernetes", profile = "control-plane" }
|
||||
{ name = "containerd", profile = "default" }
|
||||
{ name = "cilium", profile = "default" }
|
||||
]
|
||||
```
|
||||
|
||||
**Select servers to deploy:**
|
||||
|
||||
```bash
|
||||
# Choose which server groups to deploy
|
||||
all_servers = web_servers + db_servers # Web + DB only
|
||||
# OR
|
||||
all_servers = k8s_control + k8s_workers # Kubernetes cluster only
|
||||
# OR
|
||||
all_servers = web_servers + db_servers + k8s_control + k8s_workers # Everything
|
||||
```
|
||||
|
||||
### 3. Deploy
|
||||
|
||||
```bash
|
||||
# Test configuration
|
||||
kcl run servers.k
|
||||
|
||||
# Dry-run deployment (recommended)
|
||||
provisioning s create --infra <name> --check
|
||||
|
||||
# Deploy selected servers
|
||||
provisioning s create --infra <name>
|
||||
|
||||
# Or deploy specific server groups
|
||||
provisioning s create --infra <name> --select web
|
||||
```
|
||||
|
||||
## Architecture Examples
|
||||
|
||||
### Web Application Stack
|
||||
|
||||
Deploy web servers + database:
|
||||
|
||||
```bash
|
||||
all_servers = web_servers + db_servers
|
||||
```
|
||||
|
||||
### Kubernetes Cluster
|
||||
|
||||
Deploy control plane + workers:
|
||||
|
||||
```bash
|
||||
all_servers = k8s_control + k8s_workers
|
||||
```
|
||||
|
||||
### Complete Infrastructure
|
||||
|
||||
Deploy everything:
|
||||
|
||||
```bash
|
||||
all_servers = web_servers + db_servers + k8s_control + k8s_workers
|
||||
```
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Network Segmentation
|
||||
|
||||
- **Public servers**: web-01, web-02 (public + private networks)
|
||||
- **Private servers**: db-01 (private network only)
|
||||
- **Hybrid**: k8s nodes (public for API access, private for pod networking)
|
||||
|
||||
### Monitoring
|
||||
|
||||
Monitoring is pre-configured in settings:
|
||||
|
||||
```toml
|
||||
monitoring = {
|
||||
enabled = True
|
||||
metrics_port = 9100
|
||||
log_aggregation = True
|
||||
}
|
||||
```
|
||||
|
||||
### SSH Configuration
|
||||
|
||||
Advanced SSH settings are included:
|
||||
|
||||
```toml
|
||||
ssh_config = {
|
||||
connect_timeout = 30
|
||||
retry_attempts = 3
|
||||
compression = True
|
||||
}
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Customize server specs** - Adjust CPU, memory, storage
|
||||
2. **Configure networking** - Set up firewall rules, load balancers
|
||||
3. **Add taskservs** - Uncomment and configure task services
|
||||
4. **Set up clusters** - Deploy Kubernetes or container clusters
|
||||
5. **Configure monitoring** - Set up metrics and logging
|
||||
6. **Implement backup** - Configure backup policies
|
||||
|
||||
## Template Characteristics
|
||||
|
||||
- **Complexity**: High
|
||||
- **Servers**: 6 examples (web, database, k8s)
|
||||
- **Pre-configured modules**: Examples for all major components
|
||||
- **Best for**: Production deployments, complex architectures, learning advanced patterns
|
||||
@ -1 +1,59 @@
|
||||
# Minimal Infrastructure Template\n\nThis is a minimal infrastructure template with a basic server configuration.\n\n## What's Included\n\n- **Single server definition** - Basic example to customize\n- **Minimal settings** - Essential configuration only\n- **No pre-configured modules** - Load what you need\n\n## Quick Start\n\n### 1. Load Required Modules\n\n```\ncd infra/<your-infra-name>\n\n# Load a provider\nprovisioning mod load providers . upcloud\n\n# Load taskservs as needed\nprovisioning mod load taskservs . containerd\n```\n\n### 2. Customize Configuration\n\nEdit `servers.k`:\n\n- Change server hostname and title\n- Configure network settings\n- Add provider-specific settings (plan, storage, etc.)\n- Add taskservs when ready\n\n### 3. Deploy\n\n```\n# Test configuration\nkcl run servers.k\n\n# Dry-run deployment\nprovisioning s create --infra <name> --check\n\n# Deploy\nprovisioning s create --infra <name>\n```\n\n## Next Steps\n\n- Add more servers to the `example_servers` array\n- Configure taskservs for your servers\n- Set up monitoring and backup\n- Configure firewall rules\n\n## Template Characteristics\n\n- **Complexity**: Low\n- **Servers**: 1 basic example\n- **Pre-configured modules**: None\n- **Best for**: Learning, simple deployments, custom configurations
|
||||
# Minimal Infrastructure Template
|
||||
|
||||
This is a minimal infrastructure template with a basic server configuration.
|
||||
|
||||
## What's Included
|
||||
|
||||
- **Single server definition** - Basic example to customize
|
||||
- **Minimal settings** - Essential configuration only
|
||||
- **No pre-configured modules** - Load what you need
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Load Required Modules
|
||||
|
||||
```bash
|
||||
cd infra/<your-infra-name>
|
||||
|
||||
# Load a provider
|
||||
provisioning mod load providers . upcloud
|
||||
|
||||
# Load taskservs as needed
|
||||
provisioning mod load taskservs . containerd
|
||||
```
|
||||
|
||||
### 2. Customize Configuration
|
||||
|
||||
Edit `servers.k`:
|
||||
|
||||
- Change server hostname and title
|
||||
- Configure network settings
|
||||
- Add provider-specific settings (plan, storage, etc.)
|
||||
- Add taskservs when ready
|
||||
|
||||
### 3. Deploy
|
||||
|
||||
```bash
|
||||
# Test configuration
|
||||
kcl run servers.k
|
||||
|
||||
# Dry-run deployment
|
||||
provisioning s create --infra <name> --check
|
||||
|
||||
# Deploy
|
||||
provisioning s create --infra <name>
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Add more servers to the `example_servers` array
|
||||
- Configure taskservs for your servers
|
||||
- Set up monitoring and backup
|
||||
- Configure firewall rules
|
||||
|
||||
## Template Characteristics
|
||||
|
||||
- **Complexity**: Low
|
||||
- **Servers**: 1 basic example
|
||||
- **Pre-configured modules**: None
|
||||
- **Best for**: Learning, simple deployments, custom configurations
|
||||
@ -1 +1,167 @@
|
||||
# Kubernetes Workspace Setup\n\nThis template provides a complete Kubernetes cluster configuration using the package-based provisioning system.\n\n## Prerequisites\n\n1. Core provisioning package installed:\n\n ```bash\n kcl-packager.nu install --version latest\n ```\n\n2. Module loader CLI available:\n\n ```bash\n module-loader --help\n ```\n\n## Setup Steps\n\n### 1. Initialize Workspace\n\n```\n# Create workspace from template\ncp -r provisioning/templates/workspaces/kubernetes ./my-k8s-cluster\ncd my-k8s-cluster\n\n# Initialize directory structure\nworkspace-init.nu . init\n```\n\n### 2. Load Required Taskservs\n\n```\n# Load Kubernetes components\nmodule-loader load taskservs . [kubernetes, cilium, containerd]\n\n# Verify loading\nmodule-loader list taskservs .\n```\n\n### 3. Load Cloud Provider\n\n```\n# For UpCloud\nmodule-loader load providers . [upcloud]\n\n# For AWS\nmodule-loader load providers . [aws]\n\n# For local development\nmodule-loader load providers . [local]\n```\n\n### 4. Configure Infrastructure\n\n1. Edit `servers.k` to uncomment the import statements and taskserv configurations\n2. Adjust server specifications, hostnames, and labels as needed\n3. Configure provider-specific settings in the generated provider files\n\n### 5. Validate Configuration\n\n```\n# Validate KCL configuration\nkcl run servers.k\n\n# Validate workspace\nmodule-loader validate .\n```\n\n### 6. Deploy Cluster\n\n```\n# Create servers\nprovisioning server create --infra . --check\n\n# Install taskservs\nprovisioning taskserv create kubernetes --infra .\nprovisioning taskserv create cilium --infra .\nprovisioning taskserv create containerd --infra .\n\n# Verify cluster\nkubectl get nodes\n```\n\n## Configuration Details\n\n### Server Roles\n\n- **k8s-master-01**: Control plane node running the Kubernetes API server, etcd, and scheduler\n- **k8s-worker-01/02**: Worker nodes running kubelet and container runtime\n\n### Taskservs\n\n- **containerd**: Container runtime for Kubernetes\n- **kubernetes**: Core Kubernetes components (kubelet, kubeadm, kubectl)\n- **cilium**: CNI (Container Network Interface) for pod networking\n\n### Network Configuration\n\n- All nodes have public IPv4 for initial setup\n- Cilium provides internal pod-to-pod networking\n- SSH access on port 22 for management\n\n## Customization\n\n### Adding More Workers\n\nCopy the worker node configuration in `servers.k` and modify:\n\n- `hostname`\n- `title`\n- Any provider-specific settings\n\n### Different Container Runtime\n\nReplace `containerd` taskserv with:\n\n- `crio`: CRI-O runtime\n- `docker`: Docker runtime (not recommended for production)\n\n### Different CNI\n\nReplace `cilium` taskserv with:\n\n- `calico`: Calico CNI\n- `flannel`: Flannel CNI\n- Built-in kubenet (remove CNI taskserv)\n\n### Storage\n\nAdd storage taskservs:\n\n```\nmodule-loader load taskservs . [rook-ceph, mayastor]\n```\n\nThen add to server taskserv configurations:\n\n```\ntaskservs = [\n { name = "containerd", profile = "default" },\n { name = "kubernetes", profile = "worker" },\n { name = "cilium", profile = "worker" },\n { name = "rook-ceph", profile = "default" }\n]\n```\n\n## Troubleshooting\n\n### Module Import Errors\n\nIf you see import errors like "module not found":\n\n1. Verify modules are loaded: `module-loader list taskservs .`\n2. Check generated import files: `ls .taskservs/`\n3. Reload modules if needed: `module-loader load taskservs . [kubernetes, cilium, containerd]`\n\n### Provider Configuration\n\nCheck provider-specific configuration in `.providers/` directory after loading.\n\n### Kubernetes Setup Issues\n\n1. Check taskserv installation logs in `./tmp/k8s-deployment/`\n2. Verify all nodes are reachable via SSH\n3. Check firewall rules for Kubernetes ports (6443, 10250, etc.)
|
||||
# Kubernetes Workspace Setup
|
||||
|
||||
This template provides a complete Kubernetes cluster configuration using the package-based provisioning system.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. Core provisioning package installed:
|
||||
|
||||
```bash
|
||||
kcl-packager.nu install --version latest
|
||||
```
|
||||
|
||||
2. Module loader CLI available:
|
||||
|
||||
```bash
|
||||
module-loader --help
|
||||
```
|
||||
|
||||
## Setup Steps
|
||||
|
||||
### 1. Initialize Workspace
|
||||
|
||||
```bash
|
||||
# Create workspace from template
|
||||
cp -r provisioning/templates/workspaces/kubernetes ./my-k8s-cluster
|
||||
cd my-k8s-cluster
|
||||
|
||||
# Initialize directory structure
|
||||
workspace-init.nu . init
|
||||
```
|
||||
|
||||
### 2. Load Required Taskservs
|
||||
|
||||
```bash
|
||||
# Load Kubernetes components
|
||||
module-loader load taskservs . [kubernetes, cilium, containerd]
|
||||
|
||||
# Verify loading
|
||||
module-loader list taskservs .
|
||||
```
|
||||
|
||||
### 3. Load Cloud Provider
|
||||
|
||||
```bash
|
||||
# For UpCloud
|
||||
module-loader load providers . [upcloud]
|
||||
|
||||
# For AWS
|
||||
module-loader load providers . [aws]
|
||||
|
||||
# For local development
|
||||
module-loader load providers . [local]
|
||||
```
|
||||
|
||||
### 4. Configure Infrastructure
|
||||
|
||||
1. Edit `servers.k` to uncomment the import statements and taskserv configurations
|
||||
2. Adjust server specifications, hostnames, and labels as needed
|
||||
3. Configure provider-specific settings in the generated provider files
|
||||
|
||||
### 5. Validate Configuration
|
||||
|
||||
```toml
|
||||
# Validate KCL configuration
|
||||
kcl run servers.k
|
||||
|
||||
# Validate workspace
|
||||
module-loader validate .
|
||||
```
|
||||
|
||||
### 6. Deploy Cluster
|
||||
|
||||
```bash
|
||||
# Create servers
|
||||
provisioning server create --infra . --check
|
||||
|
||||
# Install taskservs
|
||||
provisioning taskserv create kubernetes --infra .
|
||||
provisioning taskserv create cilium --infra .
|
||||
provisioning taskserv create containerd --infra .
|
||||
|
||||
# Verify cluster
|
||||
kubectl get nodes
|
||||
```
|
||||
|
||||
## Configuration Details
|
||||
|
||||
### Server Roles
|
||||
|
||||
- **k8s-master-01**: Control plane node running the Kubernetes API server, etcd, and scheduler
|
||||
- **k8s-worker-01/02**: Worker nodes running kubelet and container runtime
|
||||
|
||||
### Taskservs
|
||||
|
||||
- **containerd**: Container runtime for Kubernetes
|
||||
- **kubernetes**: Core Kubernetes components (kubelet, kubeadm, kubectl)
|
||||
- **cilium**: CNI (Container Network Interface) for pod networking
|
||||
|
||||
### Network Configuration
|
||||
|
||||
- All nodes have public IPv4 for initial setup
|
||||
- Cilium provides internal pod-to-pod networking
|
||||
- SSH access on port 22 for management
|
||||
|
||||
## Customization
|
||||
|
||||
### Adding More Workers
|
||||
|
||||
Copy the worker node configuration in `servers.k` and modify:
|
||||
|
||||
- `hostname`
|
||||
- `title`
|
||||
- Any provider-specific settings
|
||||
|
||||
### Different Container Runtime
|
||||
|
||||
Replace `containerd` taskserv with:
|
||||
|
||||
- `crio`: CRI-O runtime
|
||||
- `docker`: Docker runtime (not recommended for production)
|
||||
|
||||
### Different CNI
|
||||
|
||||
Replace `cilium` taskserv with:
|
||||
|
||||
- `calico`: Calico CNI
|
||||
- `flannel`: Flannel CNI
|
||||
- Built-in kubenet (remove CNI taskserv)
|
||||
|
||||
### Storage
|
||||
|
||||
Add storage taskservs:
|
||||
|
||||
```bash
|
||||
module-loader load taskservs . [rook-ceph, mayastor]
|
||||
```
|
||||
|
||||
Then add to server taskserv configurations:
|
||||
|
||||
```toml
|
||||
taskservs = [
|
||||
{ name = "containerd", profile = "default" },
|
||||
{ name = "kubernetes", profile = "worker" },
|
||||
{ name = "cilium", profile = "worker" },
|
||||
{ name = "rook-ceph", profile = "default" }
|
||||
]
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Module Import Errors
|
||||
|
||||
If you see import errors like "module not found":
|
||||
|
||||
1. Verify modules are loaded: `module-loader list taskservs .`
|
||||
2. Check generated import files: `ls .taskservs/`
|
||||
3. Reload modules if needed: `module-loader load taskservs . [kubernetes, cilium, containerd]`
|
||||
|
||||
### Provider Configuration
|
||||
|
||||
Check provider-specific configuration in `.providers/` directory after loading.
|
||||
|
||||
### Kubernetes Setup Issues
|
||||
|
||||
1. Check taskserv installation logs in `./tmp/k8s-deployment/`
|
||||
2. Verify all nodes are reachable via SSH
|
||||
3. Check firewall rules for Kubernetes ports (6443, 10250, etc.)
|
||||
File diff suppressed because one or more lines are too long
156
tools/README.md
156
tools/README.md
@ -1 +1,155 @@
|
||||
# Development Tools\n\nDevelopment and distribution tooling for provisioning.\n\n## Tool Categories\n\n### Build Tools (`build/`)\n\nBuild automation and compilation tools:\n\n- Nushell script validation\n- KCL schema compilation\n- Dependency management\n- Asset bundling\n\n**Future Features**:\n\n- Automated testing pipelines\n- Code quality checks\n- Performance benchmarking\n\n### Package Tools (`package/`)\n\nPackaging utilities for distribution:\n\n- Standalone executables\n- Container images\n- System packages (deb, rpm, etc.)\n- Archive creation\n\n**Future Features**:\n\n- Multi-platform builds\n- Dependency bundling\n- Signature verification\n\n### Release Tools (`release/`)\n\nRelease management automation:\n\n- Version bumping\n- Changelog generation\n- Git tag management\n- Release notes creation\n\n**Future Features**:\n\n- Automated GitHub releases\n- Asset uploads\n- Release validation\n\n### Distribution Tools (`distribution/`)\n\nDistribution generators and deployment:\n\n- Installation scripts\n- Configuration templates\n- Update mechanisms\n- Registry management\n\n**Future Features**:\n\n- Package repositories\n- Update servers\n- Telemetry collection\n\n## Tool Architecture\n\n### Script-Based Tools\n\nMost tools are implemented as Nushell scripts for consistency with the main system:\n\n- Easy integration with existing codebase\n- Consistent configuration handling\n- Native data structure support\n\n### Build Pipeline Integration\n\nTools integrate with common CI/CD systems:\n\n- GitHub Actions\n- GitLab CI\n- Jenkins\n- Custom automation\n\n### Configuration Management\n\nTools use the same configuration system as the main application:\n\n- Unified settings\n- Environment-specific overrides\n- Secret management integration\n\n## Usage Examples\n\n```\n# Build the complete system\n./tools/build/build-all.nu\n\n# Package for distribution\n./tools/package/create-standalone.nu --target linux\n\n# Create a release\n./tools/release/prepare-release.nu --version 4.0.0\n\n# Generate distribution assets\n./tools/distribution/generate-installer.nu --platform macos\n```\n\n## Directory Structure\n\n```\nprovisioning/tools/\n├── README.md # This file\n├── build/ # Core build tools (Rust + Nushell)\n│ ├── README.md\n│ ├── compile-platform.nu # Compile Rust binaries\n│ ├── bundle-core.nu # Bundle Nushell libraries\n│ └── check-system.nu # Validate build environment\n├── dist/ # Build output directory (generated)\n│ ├── README.md\n│ ├── core/ # Nushell bundles\n│ ├── platform/ # Compiled binaries\n│ └── config/ # Configuration files\n├── distribution/ # Distribution generation\n│ ├── README.md\n│ └── generate-distribution.nu # Create installable packages\n├── package/ # Package outputs (generated)\n│ └── README.md\n├── release/ # Release management (generated)\n│ └── README.md\n├── scripts/ # Utility and setup scripts\n│ ├── *.nu files # Nushell utilities\n│ └── *.sh files # Shell scripts\n└── [Other utility scripts] # Standalone tools\n```\n\nSee individual README.md files in each subdirectory for detailed information.\n\n## Development Setup\n\n1. Ensure all dependencies are installed\n2. Configure build environment\n3. Run initial setup scripts\n4. Validate tool functionality\n\n## Integration\n\nThese tools integrate with:\n\n- Main provisioning system\n- Extension system\n- Configuration management\n- Documentation generation\n- CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins)
|
||||
# Development Tools
|
||||
|
||||
Development and distribution tooling for provisioning.
|
||||
|
||||
## Tool Categories
|
||||
|
||||
### Build Tools (`build/`)
|
||||
|
||||
Build automation and compilation tools:
|
||||
|
||||
- Nushell script validation
|
||||
- KCL schema compilation
|
||||
- Dependency management
|
||||
- Asset bundling
|
||||
|
||||
**Future Features**:
|
||||
|
||||
- Automated testing pipelines
|
||||
- Code quality checks
|
||||
- Performance benchmarking
|
||||
|
||||
### Package Tools (`package/`)
|
||||
|
||||
Packaging utilities for distribution:
|
||||
|
||||
- Standalone executables
|
||||
- Container images
|
||||
- System packages (deb, rpm, etc.)
|
||||
- Archive creation
|
||||
|
||||
**Future Features**:
|
||||
|
||||
- Multi-platform builds
|
||||
- Dependency bundling
|
||||
- Signature verification
|
||||
|
||||
### Release Tools (`release/`)
|
||||
|
||||
Release management automation:
|
||||
|
||||
- Version bumping
|
||||
- Changelog generation
|
||||
- Git tag management
|
||||
- Release notes creation
|
||||
|
||||
**Future Features**:
|
||||
|
||||
- Automated GitHub releases
|
||||
- Asset uploads
|
||||
- Release validation
|
||||
|
||||
### Distribution Tools (`distribution/`)
|
||||
|
||||
Distribution generators and deployment:
|
||||
|
||||
- Installation scripts
|
||||
- Configuration templates
|
||||
- Update mechanisms
|
||||
- Registry management
|
||||
|
||||
**Future Features**:
|
||||
|
||||
- Package repositories
|
||||
- Update servers
|
||||
- Telemetry collection
|
||||
|
||||
## Tool Architecture
|
||||
|
||||
### Script-Based Tools
|
||||
|
||||
Most tools are implemented as Nushell scripts for consistency with the main system:
|
||||
|
||||
- Easy integration with existing codebase
|
||||
- Consistent configuration handling
|
||||
- Native data structure support
|
||||
|
||||
### Build Pipeline Integration
|
||||
|
||||
Tools integrate with common CI/CD systems:
|
||||
|
||||
- GitHub Actions
|
||||
- GitLab CI
|
||||
- Jenkins
|
||||
- Custom automation
|
||||
|
||||
### Configuration Management
|
||||
|
||||
Tools use the same configuration system as the main application:
|
||||
|
||||
- Unified settings
|
||||
- Environment-specific overrides
|
||||
- Secret management integration
|
||||
|
||||
## Usage Examples
|
||||
|
||||
```bash
|
||||
# Build the complete system
|
||||
./tools/build/build-all.nu
|
||||
|
||||
# Package for distribution
|
||||
./tools/package/create-standalone.nu --target linux
|
||||
|
||||
# Create a release
|
||||
./tools/release/prepare-release.nu --version 4.0.0
|
||||
|
||||
# Generate distribution assets
|
||||
./tools/distribution/generate-installer.nu --platform macos
|
||||
```
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```bash
|
||||
provisioning/tools/
|
||||
├── README.md # This file
|
||||
├── build/ # Core build tools (Rust + Nushell)
|
||||
│ ├── README.md
|
||||
│ ├── compile-platform.nu # Compile Rust binaries
|
||||
│ ├── bundle-core.nu # Bundle Nushell libraries
|
||||
│ └── check-system.nu # Validate build environment
|
||||
├── dist/ # Build output directory (generated)
|
||||
│ ├── README.md
|
||||
│ ├── core/ # Nushell bundles
|
||||
│ ├── platform/ # Compiled binaries
|
||||
│ └── config/ # Configuration files
|
||||
├── distribution/ # Distribution generation
|
||||
│ ├── README.md
|
||||
│ └── generate-distribution.nu # Create installable packages
|
||||
├── package/ # Package outputs (generated)
|
||||
│ └── README.md
|
||||
├── release/ # Release management (generated)
|
||||
│ └── README.md
|
||||
├── scripts/ # Utility and setup scripts
|
||||
│ ├── *.nu files # Nushell utilities
|
||||
│ └── *.sh files # Shell scripts
|
||||
└── [Other utility scripts] # Standalone tools
|
||||
```
|
||||
|
||||
See individual README.md files in each subdirectory for detailed information.
|
||||
|
||||
## Development Setup
|
||||
|
||||
1. Ensure all dependencies are installed
|
||||
2. Configure build environment
|
||||
3. Run initial setup scripts
|
||||
4. Validate tool functionality
|
||||
|
||||
## Integration
|
||||
|
||||
These tools integrate with:
|
||||
|
||||
- Main provisioning system
|
||||
- Extension system
|
||||
- Configuration management
|
||||
- Documentation generation
|
||||
- CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins)
|
||||
@ -1 +1,76 @@
|
||||
# Build System\n\n**Purpose**: Core build tools for compiling Rust components and bundling Nushell libraries.\n\n## Tools\n\n### Compilation\n\n- **`compile-platform.nu`** - Compile Rust orchestrator, control-center, and MCP server\n - Multi-platform cross-compilation\n - Release/debug build modes\n - Feature flag management\n - Output to `dist/platform/`\n\n### Bundling\n\n- **`bundle-core.nu`** - Bundle Nushell core libraries and CLI\n - Package provisioning CLI wrapper\n - Core library bundling (lib_provisioning)\n - Configuration system packaging\n - Validation and syntax checking\n - Optional compression (gzip)\n - Output to `dist/core/`\n\n### Validation\n\n- **`check-system.nu`** - Validate build environment\n - Check required tools (Rust, Nushell, Nickel)\n - Verify dependencies\n - Validate configuration\n\n## Build Process\n\nComplete build pipeline:\n\n```{$detected_lang}\njust build-all # Platform + core\njust build-platform # Rust binaries only\njust build-core # Nushell libraries only\n```\n\nBuild with validation:\n\n```{$detected_lang}\njust build-core --validate # Validate Nushell syntax\n```\n\nDebug build:\n\n```{$detected_lang}\njust build-debug # Build with debug symbols\n```\n\n## Output\n\nBuild outputs go to `dist/`:\n\n- `dist/platform/` - Compiled Rust binaries\n- `dist/core/` - Nushell libraries and CLI\n- `dist/config/` - Configuration files\n- `dist/core/bundle-metadata.json` - Build metadata\n\n## Architecture\n\nEach build tool follows Nushell 0.109+ standards:\n\n- Immutable variable patterns\n- Explicit external command prefixes (`^`)\n- Error handling via `do { } | complete` pattern\n- Comprehensive logging\n\n## Related Files\n\n- `provisioning/justfiles/build.just` - Build recipe definitions\n- `provisioning/tools/distribution/` - Distribution generation using build outputs\n- `provisioning/tools/package/` - Packaging compiled binaries
|
||||
# Build System
|
||||
|
||||
**Purpose**: Core build tools for compiling Rust components and bundling Nushell libraries.
|
||||
|
||||
## Tools
|
||||
|
||||
### Compilation
|
||||
|
||||
- **`compile-platform.nu`** - Compile Rust orchestrator, control-center, and MCP server
|
||||
- Multi-platform cross-compilation
|
||||
- Release/debug build modes
|
||||
- Feature flag management
|
||||
- Output to `dist/platform/`
|
||||
|
||||
### Bundling
|
||||
|
||||
- **`bundle-core.nu`** - Bundle Nushell core libraries and CLI
|
||||
- Package provisioning CLI wrapper
|
||||
- Core library bundling (lib_provisioning)
|
||||
- Configuration system packaging
|
||||
- Validation and syntax checking
|
||||
- Optional compression (gzip)
|
||||
- Output to `dist/core/`
|
||||
|
||||
### Validation
|
||||
|
||||
- **`check-system.nu`** - Validate build environment
|
||||
- Check required tools (Rust, Nushell, Nickel)
|
||||
- Verify dependencies
|
||||
- Validate configuration
|
||||
|
||||
## Build Process
|
||||
|
||||
Complete build pipeline:
|
||||
|
||||
```bash
|
||||
just build-all # Platform + core
|
||||
just build-platform # Rust binaries only
|
||||
just build-core # Nushell libraries only
|
||||
```
|
||||
|
||||
Build with validation:
|
||||
|
||||
```bash
|
||||
just build-core --validate # Validate Nushell syntax
|
||||
```
|
||||
|
||||
Debug build:
|
||||
|
||||
```bash
|
||||
just build-debug # Build with debug symbols
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
Build outputs go to `dist/`:
|
||||
|
||||
- `dist/platform/` - Compiled Rust binaries
|
||||
- `dist/core/` - Nushell libraries and CLI
|
||||
- `dist/config/` - Configuration files
|
||||
- `dist/core/bundle-metadata.json` - Build metadata
|
||||
|
||||
## Architecture
|
||||
|
||||
Each build tool follows Nushell 0.109+ standards:
|
||||
|
||||
- Immutable variable patterns
|
||||
- Explicit external command prefixes (`^`)
|
||||
- Error handling via `do { } | complete` pattern
|
||||
- Comprehensive logging
|
||||
|
||||
## Related Files
|
||||
|
||||
- `provisioning/justfiles/build.just` - Build recipe definitions
|
||||
- `provisioning/tools/distribution/` - Distribution generation using build outputs
|
||||
- `provisioning/tools/package/` - Packaging compiled binaries
|
||||
File diff suppressed because one or more lines are too long
67
tools/dist/README.md
vendored
67
tools/dist/README.md
vendored
@ -1 +1,66 @@
|
||||
# Distribution Build Output\n\n**Purpose**: Compiled binaries and bundled libraries ready for packaging and distribution.\n\n## Contents\n\nThis directory contains the build output from the core platform build system:\n\n### Subdirectories\n\n- **`core/`** - Nushell core libraries and CLI bundles (from `bundle-core.nu`)\n - Nushell provisioning CLI wrapper\n - Core libraries (lib_provisioning)\n - Configuration system\n - Template system\n - Extensions and plugins\n\n- **`platform/`** - Compiled Rust binaries (from `compile-platform.nu`)\n - provisioning-orchestrator binary\n - control-center binary\n - control-center-ui binary\n - mcp-server-rust binary\n - All cross-platform target binaries\n\n- **`config/`** - Configuration files and templates\n - Default configurations\n - Configuration examples\n - Schema definitions\n\n- **`provisioning-kcl-1.0.0/`** - Deprecated KCL distribution (archived)\n - Historical reference only\n - Migrated to `.coder/archive/kcl/` for long-term storage\n\n## Usage\n\nThis directory is generated by the build system. Do not commit contents to git (configured in .gitignore).\n\nBuild the distribution:\n\n```{$detected_lang}\njust build-all # Complete build (platform + core)\njust build-platform # Platform binaries only\njust build-core # Core libraries only\n```\n\nView distribution contents:\n\n```{$detected_lang}\nls dist/core/ # Nushell libraries\nls dist/platform/ # Compiled binaries\nls dist/config/ # Configuration files\n```\n\n## Cleanup\n\nRemove all distribution artifacts:\n\n```{$detected_lang}\njust clean-dist # Remove dist/ directory\n```\n\n## Related Directories\n\n- `distribution/` - Distribution package generation\n- `package/` - Package creation (deb, rpm, tar.gz, etc.)\n- `release/` - Release management and versioning
|
||||
# Distribution Build Output
|
||||
|
||||
**Purpose**: Compiled binaries and bundled libraries ready for packaging and distribution.
|
||||
|
||||
## Contents
|
||||
|
||||
This directory contains the build output from the core platform build system:
|
||||
|
||||
### Subdirectories
|
||||
|
||||
- **`core/`** - Nushell core libraries and CLI bundles (from `bundle-core.nu`)
|
||||
- Nushell provisioning CLI wrapper
|
||||
- Core libraries (lib_provisioning)
|
||||
- Configuration system
|
||||
- Template system
|
||||
- Extensions and plugins
|
||||
|
||||
- **`platform/`** - Compiled Rust binaries (from `compile-platform.nu`)
|
||||
- provisioning-orchestrator binary
|
||||
- control-center binary
|
||||
- control-center-ui binary
|
||||
- mcp-server-rust binary
|
||||
- All cross-platform target binaries
|
||||
|
||||
- **`config/`** - Configuration files and templates
|
||||
- Default configurations
|
||||
- Configuration examples
|
||||
- Schema definitions
|
||||
|
||||
- **`provisioning-kcl-1.0.0/`** - Deprecated KCL distribution (archived)
|
||||
- Historical reference only
|
||||
- Migrated to `.coder/archive/kcl/` for long-term storage
|
||||
|
||||
## Usage
|
||||
|
||||
This directory is generated by the build system. Do not commit contents to git (configured in .gitignore).
|
||||
|
||||
Build the distribution:
|
||||
|
||||
```bash
|
||||
just build-all # Complete build (platform + core)
|
||||
just build-platform # Platform binaries only
|
||||
just build-core # Core libraries only
|
||||
```
|
||||
|
||||
View distribution contents:
|
||||
|
||||
```bash
|
||||
ls dist/core/ # Nushell libraries
|
||||
ls dist/platform/ # Compiled binaries
|
||||
ls dist/config/ # Configuration files
|
||||
```
|
||||
|
||||
## Cleanup
|
||||
|
||||
Remove all distribution artifacts:
|
||||
|
||||
```bash
|
||||
just clean-dist # Remove dist/ directory
|
||||
```
|
||||
|
||||
## Related Directories
|
||||
|
||||
- `distribution/` - Distribution package generation
|
||||
- `package/` - Package creation (deb, rpm, tar.gz, etc.)
|
||||
- `release/` - Release management and versioning
|
||||
@ -1 +1,58 @@
|
||||
# Distribution Package Generation\n\n**Purpose**: Generate complete distribution packages from compiled binaries and libraries.\n\n## Contents\n\nScripts and outputs for creating distribution-ready packages across multiple platforms and formats.\n\n## What is Distribution Generation\n\nDistribution generation takes the compiled artifacts from `dist/` and packages them into:\n\n- Installable archives (tar.gz, zip)\n- Platform-specific installers (deb, rpm, brew)\n- Docker/container images\n- Binary distributions with configuration templates\n\n## Build Process\n\nThe distribution build system:\n\n1. Takes binaries from `dist/platform/`\n2. Takes libraries from `dist/core/`\n3. Takes configuration templates from `dist/config/`\n4. Combines with installation scripts\n5. Creates platform-specific packages\n\nGenerate a distribution:\n\n```{$detected_lang}\njust dist-generate # Full distribution generation\njust dist-validate # Validate generated distribution\n```\n\n## Output Artifacts\n\nGenerated distribution includes:\n\n- Compiled binaries (orchestrator, control-center, MCP server)\n- Installation script (install.sh)\n- Configuration templates\n- Documentation\n- License files\n\n## Related Directories\n\n- `dist/` - Build output (source for distribution)\n- `package/` - Alternative packaging (low-level format creation)\n- `release/` - Version management and release tagging\n\n## Integration\n\nThe distribution output is used by:\n\n- Installation system (`provisioning-installer`)\n- Package managers\n- CI/CD pipelines\n- End-user downloads
|
||||
# Distribution Package Generation
|
||||
|
||||
**Purpose**: Generate complete distribution packages from compiled binaries and libraries.
|
||||
|
||||
## Contents
|
||||
|
||||
Scripts and outputs for creating distribution-ready packages across multiple platforms and formats.
|
||||
|
||||
## What is Distribution Generation
|
||||
|
||||
Distribution generation takes the compiled artifacts from `dist/` and packages them into:
|
||||
|
||||
- Installable archives (tar.gz, zip)
|
||||
- Platform-specific installers (deb, rpm, brew)
|
||||
- Docker/container images
|
||||
- Binary distributions with configuration templates
|
||||
|
||||
## Build Process
|
||||
|
||||
The distribution build system:
|
||||
|
||||
1. Takes binaries from `dist/platform/`
|
||||
2. Takes libraries from `dist/core/`
|
||||
3. Takes configuration templates from `dist/config/`
|
||||
4. Combines with installation scripts
|
||||
5. Creates platform-specific packages
|
||||
|
||||
Generate a distribution:
|
||||
|
||||
```bash
|
||||
just dist-generate # Full distribution generation
|
||||
just dist-validate # Validate generated distribution
|
||||
```
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
Generated distribution includes:
|
||||
|
||||
- Compiled binaries (orchestrator, control-center, MCP server)
|
||||
- Installation script (install.sh)
|
||||
- Configuration templates
|
||||
- Documentation
|
||||
- License files
|
||||
|
||||
## Related Directories
|
||||
|
||||
- `dist/` - Build output (source for distribution)
|
||||
- `package/` - Alternative packaging (low-level format creation)
|
||||
- `release/` - Version management and release tagging
|
||||
|
||||
## Integration
|
||||
|
||||
The distribution output is used by:
|
||||
|
||||
- Installation system (`provisioning-installer`)
|
||||
- Package managers
|
||||
- CI/CD pipelines
|
||||
- End-user downloads
|
||||
@ -1 +1,187 @@
|
||||
# Nickel Installation Guide\n\n## Overview\n\nNickel is a configuration language that complements KCL in the provisioning system. It provides:\n\n- Lazy evaluation for efficient configuration processing\n- Modern functional programming paradigms\n- Excellent integration with the CLI daemon for config rendering\n\n## Installation Methods\n\n### Recommended: Nix (Official Method)\n\nNickel is maintained by Tweag and officially recommends Nix for installation. This avoids all dependency issues:\n\n```\n# Install Nix (one-time setup) - Using official NixOS installer\ncurl https://nixos.org/nix/install | sh\n\n# Install Nickel via Nix\nnix profile install nixpkgs#nickel\n\n# Verify installation\nnickel --version\n```\n\n**Why Nix?**\n\n- Isolated, reproducible environments\n- No system library conflicts\n- Official Nickel distribution method\n- Works on macOS, Linux, and other Unix-like systems\n- Pre-built binaries available\n\n### Alternative: Automatic Installation\n\nThe provisioning system can automate installation:\n\n```\n# Via tools-install script (uses Nix if available)\n$PROVISIONING/core/cli/tools-install nickel\n\n# Check installation status\n$PROVISIONING/core/cli/tools-install check\n```\n\n### Alternative: Manual Installation from Source\n\nIf you have a Rust toolchain:\n\n```\ncargo install nickel-lang-cli\n```\n\n**Note**: This requires Rust compiler (slower than pre-built binaries)\n\n## Troubleshooting\n\n### "Library not loaded: /nix/store/..." Error\n\nThis occurs when using pre-built binaries without Nix installed. **Solution**: Install Nix or use Cargo:\n\n```\n# Option 1: Install Nix (recommended) - Using official NixOS installer\ncurl https://nixos.org/nix/install | sh\n\n# Then install Nickel\nnix profile install nixpkgs#nickel\n\n# Option 2: Build from source with Cargo\ncargo install nickel-lang-cli\n```\n\n### Command Not Found\n\nEnsure Nix is properly installed and in PATH:\n\n```\n# Check if Nix is installed\nwhich nix\n\n# If not found, install Nix first using official NixOS installer:\ncurl https://nixos.org/nix/install | sh\n\n# Then install Nickel\nnix profile install nixpkgs#nickel\n```\n\n### Version Mismatch\n\nTo ensure you're using the correct version:\n\n```\n# Check installed version\nnickel --version\n\n# Expected version (from provisioning/core/versions)\necho $NICKEL_VERSION\n\n# Update to latest\nnix profile upgrade '*'\n```\n\n## Integration with Provisioning System\n\n### CLI Daemon Integration\n\nNickel is integrated into the CLI daemon for configuration rendering:\n\n```\n# Render Nickel configuration via daemon\ncurl -X POST http://localhost:9091/config/render \n -H "Content-Type: application/json" \n -d '{\n "language": "nickel",\n "content": "{name = \"my-config\", enabled = true}",\n "context": {"env": "prod"}\n }'\n```\n\n### Comparison with KCL\n\n| Feature | KCL | Nickel |\n| --------- | ----- | -------- |\n| **Type System** | Gradual, OOP-style | Gradual, Functional |\n| **Evaluation** | Eager | Lazy (partial evaluation) |\n| **Performance** | Fast | Very fast (lazy) |\n| **Learning Curve** | Moderate | Functional programming knowledge helps |\n| **Use Cases** | Infrastructure schemas | Configuration merging, lazy evaluation |\n\n## Deployment Considerations\n\n### macOS M1/M2/M3 (arm64)\n\nNix automatically handles architecture:\n\n```\nnix profile install nixpkgs#nickel\n# Automatically installs arm64 binary\n```\n\n### Linux (x86_64/arm64)\n\n```\nnix profile install nixpkgs#nickel\n# Automatically installs correct architecture\n```\n\n### CI/CD Environments\n\nFor GitHub Actions or other CI/CD:\n\n```\n# .github/workflows/example.yml\n- name: Install Nickel\n run: |\n curl https://nixos.org/nix/install | sh\n nix profile install nixpkgs#nickel\n```\n\n## Resources\n\n- **Official Website**: <https://nickel-lang.org>\n- **Getting Started**: <https://nickel-lang.org/getting-started>\n- **User Manual**: <https://nickel-lang.org/user-manual>\n- **GitHub**: <https://github.com/tweag/nickel>\n- **Nix Package**: <https://search.nixos.org/packages?query=nickel>\n\n## Version Information\n\nCurrent provisioning system configuration:\n\n```\n# View configured version\ncat $PROVISIONING/core/versions | grep NICKEL_VERSION\n\n# Current: 1.15.1\n```\n\n## Support\n\nFor issues related to:\n\n- **Nickel language**: See <https://github.com/tweag/nickel/issues>\n- **Nix installation**: See <https://github.com/DeterminateSystems/nix-installer>\n- **Provisioning integration**: See the provisioning system documentation
|
||||
# Nickel Installation Guide
|
||||
|
||||
## Overview
|
||||
|
||||
Nickel is a configuration language that complements KCL in the provisioning system. It provides:
|
||||
|
||||
- Lazy evaluation for efficient configuration processing
|
||||
- Modern functional programming paradigms
|
||||
- Excellent integration with the CLI daemon for config rendering
|
||||
|
||||
## Installation Methods
|
||||
|
||||
### Recommended: Nix (Official Method)
|
||||
|
||||
Nickel is maintained by Tweag and officially recommends Nix for installation. This avoids all dependency issues:
|
||||
|
||||
```nickel
|
||||
# Install Nix (one-time setup) - Using official NixOS installer
|
||||
curl https://nixos.org/nix/install | sh
|
||||
|
||||
# Install Nickel via Nix
|
||||
nix profile install nixpkgs#nickel
|
||||
|
||||
# Verify installation
|
||||
nickel --version
|
||||
```
|
||||
|
||||
**Why Nix?**
|
||||
|
||||
- Isolated, reproducible environments
|
||||
- No system library conflicts
|
||||
- Official Nickel distribution method
|
||||
- Works on macOS, Linux, and other Unix-like systems
|
||||
- Pre-built binaries available
|
||||
|
||||
### Alternative: Automatic Installation
|
||||
|
||||
The provisioning system can automate installation:
|
||||
|
||||
```nickel
|
||||
# Via tools-install script (uses Nix if available)
|
||||
$PROVISIONING/core/cli/tools-install nickel
|
||||
|
||||
# Check installation status
|
||||
$PROVISIONING/core/cli/tools-install check
|
||||
```
|
||||
|
||||
### Alternative: Manual Installation from Source
|
||||
|
||||
If you have a Rust toolchain:
|
||||
|
||||
```rust
|
||||
cargo install nickel-lang-cli
|
||||
```
|
||||
|
||||
**Note**: This requires Rust compiler (slower than pre-built binaries)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Library not loaded: /nix/store/..." Error
|
||||
|
||||
This occurs when using pre-built binaries without Nix installed. **Solution**: Install Nix or use Cargo:
|
||||
|
||||
```rust
|
||||
# Option 1: Install Nix (recommended) - Using official NixOS installer
|
||||
curl https://nixos.org/nix/install | sh
|
||||
|
||||
# Then install Nickel
|
||||
nix profile install nixpkgs#nickel
|
||||
|
||||
# Option 2: Build from source with Cargo
|
||||
cargo install nickel-lang-cli
|
||||
```
|
||||
|
||||
### Command Not Found
|
||||
|
||||
Ensure Nix is properly installed and in PATH:
|
||||
|
||||
```nickel
|
||||
# Check if Nix is installed
|
||||
which nix
|
||||
|
||||
# If not found, install Nix first using official NixOS installer:
|
||||
curl https://nixos.org/nix/install | sh
|
||||
|
||||
# Then install Nickel
|
||||
nix profile install nixpkgs#nickel
|
||||
```
|
||||
|
||||
### Version Mismatch
|
||||
|
||||
To ensure you're using the correct version:
|
||||
|
||||
```nickel
|
||||
# Check installed version
|
||||
nickel --version
|
||||
|
||||
# Expected version (from provisioning/core/versions)
|
||||
echo $NICKEL_VERSION
|
||||
|
||||
# Update to latest
|
||||
nix profile upgrade '*'
|
||||
```
|
||||
|
||||
## Integration with Provisioning System
|
||||
|
||||
### CLI Daemon Integration
|
||||
|
||||
Nickel is integrated into the CLI daemon for configuration rendering:
|
||||
|
||||
```nickel
|
||||
# Render Nickel configuration via daemon
|
||||
curl -X POST http://localhost:9091/config/render
|
||||
-H "Content-Type: application/json"
|
||||
-d '{
|
||||
"language": "nickel",
|
||||
"content": "{name = \"my-config\", enabled = true}",
|
||||
"context": {"env": "prod"}
|
||||
}'
|
||||
```
|
||||
|
||||
### Comparison with KCL
|
||||
|
||||
| Feature | KCL | Nickel |
|
||||
| --------- | ----- | -------- |
|
||||
| **Type System** | Gradual, OOP-style | Gradual, Functional |
|
||||
| **Evaluation** | Eager | Lazy (partial evaluation) |
|
||||
| **Performance** | Fast | Very fast (lazy) |
|
||||
| **Learning Curve** | Moderate | Functional programming knowledge helps |
|
||||
| **Use Cases** | Infrastructure schemas | Configuration merging, lazy evaluation |
|
||||
|
||||
## Deployment Considerations
|
||||
|
||||
### macOS M1/M2/M3 (arm64)
|
||||
|
||||
Nix automatically handles architecture:
|
||||
|
||||
```nickel
|
||||
nix profile install nixpkgs#nickel
|
||||
# Automatically installs arm64 binary
|
||||
```
|
||||
|
||||
### Linux (x86_64/arm64)
|
||||
|
||||
```nickel
|
||||
nix profile install nixpkgs#nickel
|
||||
# Automatically installs correct architecture
|
||||
```
|
||||
|
||||
### CI/CD Environments
|
||||
|
||||
For GitHub Actions or other CI/CD:
|
||||
|
||||
```nickel
|
||||
# .github/workflows/example.yml
|
||||
- name: Install Nickel
|
||||
run: |
|
||||
curl https://nixos.org/nix/install | sh
|
||||
nix profile install nixpkgs#nickel
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- **Official Website**: <https://nickel-lang.org>
|
||||
- **Getting Started**: <https://nickel-lang.org/getting-started>
|
||||
- **User Manual**: <https://nickel-lang.org/user-manual>
|
||||
- **GitHub**: <https://github.com/tweag/nickel>
|
||||
- **Nix Package**: <https://search.nixos.org/packages?query=nickel>
|
||||
|
||||
## Version Information
|
||||
|
||||
Current provisioning system configuration:
|
||||
|
||||
```toml
|
||||
# View configured version
|
||||
cat $PROVISIONING/core/versions | grep NICKEL_VERSION
|
||||
|
||||
# Current: 1.15.1
|
||||
```
|
||||
|
||||
## Support
|
||||
|
||||
For issues related to:
|
||||
|
||||
- **Nickel language**: See <https://github.com/tweag/nickel/issues>
|
||||
- **Nix installation**: See <https://github.com/DeterminateSystems/nix-installer>
|
||||
- **Provisioning integration**: See the provisioning system documentation
|
||||
@ -1 +1,83 @@
|
||||
# Package Build Output\n\n**Purpose**: Platform-specific packages (deb, rpm, tar.gz, etc.) created from distribution artifacts.\n\n## Contents\n\nThis directory contains the output from package creation tools that convert distribution artifacts into system-specific formats.\n\n## Package Formats\n\nGenerated packages may include:\n\n### Linux Packages\n\n- **deb** - Debian/Ubuntu packages\n- **rpm** - RedHat/CentOS packages\n- **tar.gz** - Portable tarball archives\n- **AppImage** - Universal Linux application format\n\n### macOS Packages\n\n- **pkg** - macOS installer packages\n- **dmg** - macOS disk image\n- **tar.gz** - Portable archive\n\n### Windows Packages\n\n- **msi** - Windows installer\n- **zip** - Portable archive\n- **exe** - Self-extracting executable\n\n### Container Images\n\n- **docker** - Docker container images\n- **oci** - OCI container format\n\n## Usage\n\nThis directory is generated by the package build system. Do not commit contents to git (configured in .gitignore).\n\nCreate packages:\n\n```\njust package-all # All format packages\njust package-linux # Linux packages only\njust package-macos # macOS packages only\njust package-deb # Debian package only\n```\n\nInstall a package:\n\n```\n# Linux\nsudo dpkg -i provisioning-*.deb # Debian\nsudo rpm -i provisioning-*.rpm # RedHat\n\n# macOS\nsudo installer -pkg provisioning-*.pkg -target /\n```\n\n## Package Verification\n\nVerify package contents:\n\n```\ndpkg -c provisioning-*.deb # List Debian package contents\nrpm -ql provisioning-*.rpm # List RedHat package contents\ntar -tzf provisioning-*.tar.gz # List tarball contents\n```\n\n## Cleanup\n\nRemove all packages:\n\n```\njust clean # Clean all build artifacts\n```\n\n## Related Directories\n\n- `dist/` - Build artifacts that packages are created from\n- `distribution/` - Distribution generation (uses package outputs)\n- `release/` - Version management for packages
|
||||
# Package Build Output
|
||||
|
||||
**Purpose**: Platform-specific packages (deb, rpm, tar.gz, etc.) created from distribution artifacts.
|
||||
|
||||
## Contents
|
||||
|
||||
This directory contains the output from package creation tools that convert distribution artifacts into system-specific formats.
|
||||
|
||||
## Package Formats
|
||||
|
||||
Generated packages may include:
|
||||
|
||||
### Linux Packages
|
||||
|
||||
- **deb** - Debian/Ubuntu packages
|
||||
- **rpm** - RedHat/CentOS packages
|
||||
- **tar.gz** - Portable tarball archives
|
||||
- **AppImage** - Universal Linux application format
|
||||
|
||||
### macOS Packages
|
||||
|
||||
- **pkg** - macOS installer packages
|
||||
- **dmg** - macOS disk image
|
||||
- **tar.gz** - Portable archive
|
||||
|
||||
### Windows Packages
|
||||
|
||||
- **msi** - Windows installer
|
||||
- **zip** - Portable archive
|
||||
- **exe** - Self-extracting executable
|
||||
|
||||
### Container Images
|
||||
|
||||
- **docker** - Docker container images
|
||||
- **oci** - OCI container format
|
||||
|
||||
## Usage
|
||||
|
||||
This directory is generated by the package build system. Do not commit contents to git (configured in .gitignore).
|
||||
|
||||
Create packages:
|
||||
|
||||
```bash
|
||||
just package-all # All format packages
|
||||
just package-linux # Linux packages only
|
||||
just package-macos # macOS packages only
|
||||
just package-deb # Debian package only
|
||||
```
|
||||
|
||||
Install a package:
|
||||
|
||||
```bash
|
||||
# Linux
|
||||
sudo dpkg -i provisioning-*.deb # Debian
|
||||
sudo rpm -i provisioning-*.rpm # RedHat
|
||||
|
||||
# macOS
|
||||
sudo installer -pkg provisioning-*.pkg -target /
|
||||
```
|
||||
|
||||
## Package Verification
|
||||
|
||||
Verify package contents:
|
||||
|
||||
```bash
|
||||
dpkg -c provisioning-*.deb # List Debian package contents
|
||||
rpm -ql provisioning-*.rpm # List RedHat package contents
|
||||
tar -tzf provisioning-*.tar.gz # List tarball contents
|
||||
```
|
||||
|
||||
## Cleanup
|
||||
|
||||
Remove all packages:
|
||||
|
||||
```bash
|
||||
just clean # Clean all build artifacts
|
||||
```
|
||||
|
||||
## Related Directories
|
||||
|
||||
- `dist/` - Build artifacts that packages are created from
|
||||
- `distribution/` - Distribution generation (uses package outputs)
|
||||
- `release/` - Version management for packages
|
||||
@ -1 +1,72 @@
|
||||
# Release Management Output\n\n**Purpose**: Release artifacts, version tags, and release notes.\n\n## Contents\n\nThis directory contains outputs and staging for release management operations.\n\n## Release Process\n\nRelease management handles:\n\n1. **Version Bumping** - Update version numbers across the project\n2. **Changelog Generation** - Create release notes from git history\n3. **Git Tagging** - Create git tags for releases\n4. **Release Notes** - Write comprehensive release documentation\n\n## Release Workflow\n\nPrepare a release:\n\n```\njust release-prepare --version 4.0.0 # Prepare new release\njust release-validate # Validate release readiness\n```\n\nCreate release artifacts:\n\n```\njust release-build # Build final release packages\njust release-tag # Create git tags\n```\n\nPublish release:\n\n```\njust release-publish # Upload to repositories\n```\n\n## Version Management\n\nVersions follow semantic versioning: `MAJOR.MINOR.PATCH`\n\n- **MAJOR** - Breaking changes\n- **MINOR** - New features (backward compatible)\n- **PATCH** - Bug fixes\n\nExample: `4.2.1` = Major 4, Minor 2, Patch 1\n\n## Release Artifacts\n\nA release includes:\n\n- Version-tagged binaries\n- Changelog with all changes\n- Release notes with highlights\n- Git tags for all milestones\n- Published packages in repositories\n\n## Cleanup\n\nRemove release artifacts:\n\n```\njust clean # Clean all build artifacts\n```\n\n## Related Directories\n\n- `dist/` - Build artifacts that releases are based on\n- `package/` - Packages that get versioned and released\n- `distribution/` - Distribution that incorporates release versions
|
||||
# Release Management Output
|
||||
|
||||
**Purpose**: Release artifacts, version tags, and release notes.
|
||||
|
||||
## Contents
|
||||
|
||||
This directory contains outputs and staging for release management operations.
|
||||
|
||||
## Release Process
|
||||
|
||||
Release management handles:
|
||||
|
||||
1. **Version Bumping** - Update version numbers across the project
|
||||
2. **Changelog Generation** - Create release notes from git history
|
||||
3. **Git Tagging** - Create git tags for releases
|
||||
4. **Release Notes** - Write comprehensive release documentation
|
||||
|
||||
## Release Workflow
|
||||
|
||||
Prepare a release:
|
||||
|
||||
```bash
|
||||
just release-prepare --version 4.0.0 # Prepare new release
|
||||
just release-validate # Validate release readiness
|
||||
```
|
||||
|
||||
Create release artifacts:
|
||||
|
||||
```bash
|
||||
just release-build # Build final release packages
|
||||
just release-tag # Create git tags
|
||||
```
|
||||
|
||||
Publish release:
|
||||
|
||||
```bash
|
||||
just release-publish # Upload to repositories
|
||||
```
|
||||
|
||||
## Version Management
|
||||
|
||||
Versions follow semantic versioning: `MAJOR.MINOR.PATCH`
|
||||
|
||||
- **MAJOR** - Breaking changes
|
||||
- **MINOR** - New features (backward compatible)
|
||||
- **PATCH** - Bug fixes
|
||||
|
||||
Example: `4.2.1` = Major 4, Minor 2, Patch 1
|
||||
|
||||
## Release Artifacts
|
||||
|
||||
A release includes:
|
||||
|
||||
- Version-tagged binaries
|
||||
- Changelog with all changes
|
||||
- Release notes with highlights
|
||||
- Git tags for all milestones
|
||||
- Published packages in repositories
|
||||
|
||||
## Cleanup
|
||||
|
||||
Remove release artifacts:
|
||||
|
||||
```bash
|
||||
just clean # Clean all build artifacts
|
||||
```
|
||||
|
||||
## Related Directories
|
||||
|
||||
- `dist/` - Build artifacts that releases are based on
|
||||
- `package/` - Packages that get versioned and released
|
||||
- `distribution/` - Distribution that incorporates release versions
|
||||
File diff suppressed because one or more lines are too long
Loading…
x
Reference in New Issue
Block a user