diff --git a/.gitignore b/.gitignore index 8d53365..f134411 100644 --- a/.gitignore +++ b/.gitignore @@ -27,3 +27,6 @@ chronodash-*.tar # Env files .env + +# VsCode files +.vscode/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e92907c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,238 @@ +# Contributing to Chronodash + +Thank you for taking the time to contribute to Chronodash 🚀 +Please read this guide before opening a PR to keep the codebase clean and consistent. + +--- + +## Table of Contents + +- [Development Setup](#development-setup) +- [Project Structure](#project-structure) +- [Branching Strategy](#branching-strategy) +- [Commit Convention](#commit-convention) +- [Pull Requests](#pull-requests) +- [Code Style](#code-style) +- [Testing](#testing) +- [Reporting Bugs](#reporting-bugs) + +--- + +## Development Setup + +### Prerequisites + +Make sure you have the following installed: + +- **Elixir** `~> 1.15` +- **PostgreSQL** (or use the included Docker setup) +### Steps + +1. **Clone the repository** + + ```bash + git clone + cd chronodash + ``` + +2. **Install Elixir dependencies** + + ```bash + mix deps.get + ``` + +3. **Configure environment variables** + + ```bash + cp .env.example .env + # Edit .env with your local database credentials + ``` + +4. **Start PostgreSQL with Docker (optional)** + + ```bash + docker compose up -d + ``` + +5. **Create and migrate the database** + + ```bash + mix ecto.setup + ``` + +6. **Start the backend server** + + ```bash + mix phx.server + # API available at http://localhost:4000 + ``` + +--- + +## Project Structure + +``` +chronodash/ +├── lib/ +│ ├── chronodash/ # Business logic (Ash resources, contexts) +│ │ └── accounts/ # User authentication context +│ └── chronodash_web/ # Phoenix web layer +│ ├── controllers/ # API controllers +│ └── router.ex # Route definitions +├── priv/ +│ └── repo/migrations/ # Ecto database migrations +├── config/ # Environment configuration +└── test/ # Tests +``` + +--- + +## Branching Strategy + +Always branch off from `main`. Use descriptive names with the following prefixes: + +| Prefix | Use case | +| ----------- | ------------------------------------------ | +| `feat/` | New feature | +| `fix/` | Bug fix | +| `docs/` | Documentation only | +| `refactor/` | Code restructuring without behavior change | +| `test/` | Adding or updating tests | +| `chore/` | Maintenance, dependencies, config | + +**Examples:** + +``` +feat/user-registration-endpoint +fix/cors-preflight-headers +docs/update-security-policy +chore/update-ash-dependency +``` + +--- + +## Commit Convention + +We follow [Conventional Commits](https://www.conventionalcommits.org/). + +### Format + +``` +(): + +[optional body] +``` + +### Types + +| Type | When to use | +| ---------- | ------------------------------- | +| `feat` | A new feature | +| `fix` | A bug fix | +| `docs` | Documentation changes | +| `refactor` | Refactoring without feature/fix | +| `test` | Adding or updating tests | +| `chore` | Maintenance, deps, tooling | +| `perf` | Performance improvements | + +### Examples + +```bash +feat(auth): add user registration endpoint +fix(router): handle missing CORS preflight options +docs(contributing): add project structure section +chore(deps): update ash_postgres to 2.1 +``` + +--- + +## Pull Requests + +Before submitting a PR, make sure all of the following pass: + +```bash +# 1. All tests pass +mix test + +# 2. Code is properly formatted +mix format + +# 3. No unused dependencies +mix deps.unlock --unused + +# 4. Full precommit check (runs all of the above) +mix precommit +``` + +### PR Checklist + +- [ ] Branch is up to date with `main` +- [ ] `mix precommit` passes without errors +- [ ] New functionality has tests +- [ ] No secrets or credentials committed +- [ ] PR description explains **what** changed and **why** + +### PR Description Template + +``` +## What does this PR do? +Brief description of the change. + +## Why? +Context or motivation. + +## How to test it? +Steps to verify the change works. + +## Related issues +Closes # (if applicable) +``` + +--- + +## Code Style + +This project uses `mix format` for automatic formatting. Run it before every commit. + +Additional guidelines: + +- Keep functions small and focused — one responsibility per function +- Use descriptive variable and function names in English +- Add `@doc` comments to public functions in contexts and modules +- Avoid hardcoding values — use environment variables or config files +- In the frontend, keep components in `PascalCase` and utilities in `camelCase` + +--- + +## Testing + +Run the full test suite with: + +```bash +mix test +``` + +When adding new features: + +- Add unit tests for context functions (`Chronodash.Accounts`, etc.) +- Add controller tests for new API endpoints +- Test both the happy path and error cases (invalid input, missing fields, duplicate email, etc.) + +--- + +## Reporting Bugs + +Found a bug? Please check if it's already reported in the [issues](../../issues) before opening a new one. + +For **security vulnerabilities**, do NOT open a public issue — see [SECURITY.md](./SECURITY.md) instead. + +When opening a bug report, include: + +- What you expected to happen +- What actually happened +- Steps to reproduce +- Elixir/Node version and OS + +--- + +_We appreciate every contribution, big or small. Thanks for helping make Chronodash better!_ 🙌 diff --git a/README.md b/README.md index e0062bb..98f715c 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,116 @@ Chronodash is a multi-datasource monitoring and monitoring application built wit ├── chronodash/ # Core logic tests └── support/ # Mock clients and test cases ``` +feat/add-docs +# Dependencies +This document lists all dependencies used in Chronodash, their purpose, and relevant version information. + +--- + +## Core Stack + +| Technology | Version | Purpose | +|------------|---------|---------| +| [Elixir](https://elixir-lang.org/) | `~> 1.15` | Primary programming language | +| [Phoenix Framework](https://phoenixframework.org/) | `~> 1.8.1` | Web framework and API layer | +| [PostgreSQL](https://www.postgresql.org/) | latest | Primary relational database | +| [Docker](https://www.docker.com/) | latest | Local development environment | + +--- + +## Backend Dependencies + +### Framework & Web + +| Package | Version | Purpose | License | +|---------|---------|---------|---------| +| [`phoenix`](https://hex.pm/packages/phoenix) | `~> 1.8.1` | Web framework — routing, controllers, endpoints | MIT | +| [`bandit`](https://hex.pm/packages/bandit) | `~> 1.5` | HTTP server (replaces Cowboy) | MIT | +| [`phoenix_ecto`](https://hex.pm/packages/phoenix_ecto) | `~> 4.5` | Phoenix and Ecto integration | MIT | +| [`gettext`](https://hex.pm/packages/gettext) | `~> 0.26` | Internationalization and translations | MIT | + +### Data Layer + +| Package | Version | Purpose | License | +|---------|---------|---------|---------| +| [`ecto_sql`](https://hex.pm/packages/ecto_sql) | `~> 3.13` | SQL query interface for Ecto | Apache 2.0 | +| [`postgrex`](https://hex.pm/packages/postgrex) | `>= 0.0.0` | PostgreSQL driver for Elixir | Apache 2.0 | +| [`ash`](https://hex.pm/packages/ash) | `~> 3.0` | Resource-based framework for domain modeling | MIT | +| [`ash_postgres`](https://hex.pm/packages/ash_postgres) | `~> 2.0` | AshPostgres adapter — manages migrations and repo | MIT | +| [`ash_phoenix`](https://hex.pm/packages/ash_phoenix) | `~> 2.0` | Integration between Ash and Phoenix | MIT | + +### API & Documentation + +| Package | Version | Purpose | License | +|---------|---------|---------|---------| +| [`open_api_spex`](https://hex.pm/packages/open_api_spex) | `~> 3.16` | OpenAPI 3.0 spec generation and validation | MIT | +| [`jason`](https://hex.pm/packages/jason) | `~> 1.2` | Fast JSON encoding/decoding | Apache 2.0 | + +### HTTP & Networking + +| Package | Version | Purpose | License | +|---------|---------|---------|---------| +| [`req`](https://hex.pm/packages/req) | `~> 0.5` | HTTP client for outgoing requests | Apache 2.0 | +| [`dns_cluster`](https://hex.pm/packages/dns_cluster) | `~> 0.2.0` | DNS-based node clustering | Apache 2.0 | + +### Observability + +| Package | Version | Purpose | License | +|---------|---------|---------|---------| +| [`telemetry_metrics`](https://hex.pm/packages/telemetry_metrics) | `~> 1.0` | Metrics definitions and aggregation | Apache 2.0 | +| [`telemetry_poller`](https://hex.pm/packages/telemetry_poller) | `~> 1.0` | Periodic VM and application metrics | Apache 2.0 | +| [`phoenix_live_dashboard`](https://hex.pm/packages/phoenix_live_dashboard) | `~> 0.8.3` | Real-time metrics dashboard (dev/prod) | MIT | + +### Email + +| Package | Version | Purpose | License | +|---------|---------|---------|---------| +| [`swoosh`](https://hex.pm/packages/swoosh) | `~> 1.16` | Email composition and delivery | MIT | + +### Tooling & DX + +| Package | Version | Purpose | License | +|---------|---------|---------|---------| +| [`igniter`](https://hex.pm/packages/igniter) | `~> 0.3` | Code generation and project automation | MIT | +| [`credo`](https://hex.pm/packages/credo) | `~> 1.7` | Static code analysis and style enforcement (test only) | MIT | + +--- + +## Development & Infrastructure + +| Tool | Purpose | +|------|---------| +| Docker & Docker Compose | Runs PostgreSQL locally without a manual install | +| `.env` / `.env.example` | Environment variable management | + +--- + +## Updating Dependencies + +### Elixir + +```bash +# Check for outdated packages +mix hex.outdated + +# Update a specific package +mix deps.update + +# Update all packages +mix deps.update --all + +# Check for known vulnerabilities +mix hex.audit +``` + +--- + +## Notes + +- **Ash Framework**: This project uses Ash (`~> 3.0`) as the primary domain layer. Migrations are managed by `AshPostgres` rather than plain Ecto — always use `mix ash_postgres.generate_migrations` when changing resources. +- **Bandit vs Cowboy**: This project uses `bandit` as the HTTP server. Do not add `plug_cowboy` as a dependency. +======= ## Getting Started @@ -58,3 +167,4 @@ Chronodash is a multi-datasource monitoring and monitoring application built wit 2. Configure your DB credentials in `.env`. 3. Deploy the app with telemetry: `make deploy_with_tel` 4. Access Grafana: `http://localhost:3000` (admin/admin) +main diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..b0ebf16 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,96 @@ +# Security Policy + +## Supported Versions + +| Version | Supported | +| ------- | --------- | +| main | ✅ | +| older | ❌ | + +--- + +## Reporting a Vulnerability + +If you discover a security vulnerability in Chronodash, please **do NOT open a public issue**. Public disclosure before a fix is available puts all users at risk. + +Instead, report it through one of these two channels: + +- **GitHub Private Advisory** → [Open a security advisory](https://github.com/saulzascarballal/chronodash/security/advisories/new) +- **Email** → [saulzascarballal@gmail.com](mailto:saulzascarballal@gmail.com) + +Please include as much detail as possible: + +- Clear description of the vulnerability +- Steps to reproduce it +- Affected component (auth, API, database, etc.) +- Potential impact +- Suggested fix if you have one + +We will acknowledge receipt **within 48 hours** and aim to release a patch **within 7 days** for critical issues. + +--- + +## Security Scope + +The following areas are actively monitored and considered in scope: + +### Authentication & Users + +- Unauthorized access to user accounts +- Password hashing weaknesses +- Session or token hijacking +- Brute force vulnerabilities on login endpoints + +### API Keys & Tokens + +- Exposure of API keys or secrets in logs, responses, or source code +- Insufficient token expiration or revocation +- Tokens with overly broad permissions + +### Database + +- SQL injection or query manipulation +- Unauthorized access to user data +- Data leakage through API responses +- Insecure database configuration + +--- + +## Out of Scope + +The following are **not** considered security vulnerabilities for this project: + +- Issues in unsupported/older versions +- Bugs that require physical access to the server +- Social engineering attacks +- Denial of service (DoS) via excessive requests without proof of exploitability + +--- + +## Disclosure Policy + +We follow a **responsible disclosure** process: + +1. You report the vulnerability privately +2. We confirm and investigate within 48 hours +3. We develop and test a fix +4. We release the fix and credit you (if desired) +5. Public disclosure happens after the fix is deployed + +We genuinely appreciate the work of security researchers and will always credit contributors who report valid vulnerabilities responsibly. + +--- + +## Security Best Practices for Contributors + +If you are contributing to Chronodash, please follow these guidelines: + +- Never commit secrets, API keys, or credentials to the repository +- Use environment variables for all sensitive configuration (see `.env.example`) +- Validate and sanitize all user inputs +- Do not log sensitive data (passwords, tokens, personal data) +- Keep dependencies up to date — run `mix hex.audit` regularly + +--- + +_Last updated: February 2026_