docs: add contributing, dev and security guides

docs/CONTRIBUTING.md

@@ -0,0 +1,66 @@
+# Contributing
+
+Thank you for your interest in contributing to our project! This guide will help you understand how to effectively contribute to this repository.
+
+## Getting Started
+
+Before submitting any changes, please discuss your proposed modifications with the repository maintainers by opening an issue. This step is crucial to ensure that your contributions align with the project's goals and to avoid duplicating efforts.
+
+We value meaningful contributions that substantively improve the project. Please focus on quality over quantity - contributions should address real needs or enhancement opportunities rather than superficial changes. **Proposals that appear primarily aimed at gaining contributor status without adding significant value will be declined**.
+
+For technical assistance, please refer to the [Development](docs/DEVELOPMENT.md) documentation. It contains information on setting up your development environment, running tests, and other essential details.
+
+For security-related issues, please refer to our [Security Policy](docs/SECURITY.md) for guidelines on reporting vulnerabilities and security concerns.
+
+## Code of Conduct
+
+Our community values respectful and inclusive collaboration. We strive to make participation a positive experience for everyone, regardless of background, identity, or experience level.
+
+As a contributor, we ask that you:
+
+- Treat others with respect and kindness;
+- Show empathy in your interactions;
+- Be receptive to constructive feedback;
+- Take responsibility for mistakes and use them as learning opportunities.
+
+Unacceptable behaviors may include, but are not limited to:
+
+- Harassment, bullying, or intimidation;
+- Discriminatory or offensive comments;
+- Unwelcome attention or remarks;
+- Sharing private information without permission.
+
+If you witness or experience inappropriate behavior, please contact our community leaders at legal _at_ goinfinite.net. All reports will be reviewed and addressed appropriately.
+
+Enforcements actions from correction to permanent bans will be taken depending on the severity of the violation.
+
+## Licensing
+
+This project is released under the Eclipse Public License (EPL) version 2.0. By contributing, you agree that your submissions will be governed by this license. This arrangement protects the open source nature of the project.
+
+### Contributor Agreement
+
+Contributors must sign the Fiduciary Contributor License Agreement (FLA) before submitting code. This legal agreement transfers copyright of contributions to a designated fiduciary who manages these rights for the project's benefit.
+
+The FLA serves to:
+
+- Maintain the software's free and open source status;
+- Shield the project from potential copyright complications;
+- Include a safety mechanism: if the fiduciary violates Free Software principles, rights return to the original contributors.
+
+For additional information about the FLA, please refer to the [FLA FAQ](https://fsfe.org/activities/fla/fla.en.html).
+
+## Pull Request Guidelines
+
+When submitting pull requests, please follow these steps:
+
+- Remove any build or installation dependencies before finalizing your build;
+- Document interface changes in the README.md, including new environment variables, ports, file locations, and container parameters;
+- Update version numbers according to [SemVer](http://semver.org/) conventions in relevant files (examples, CHANGELOG.md, api.go etc);
+- Add unit tests for any new features or bug fixes, specially for infrastructure, value objects and any entities or use cases that contains enough non-trivial logic;
+- Ensure all tests pass before submitting your pull request;
+- Adhere to every Clean Code Rules described at [ntorga's article](https://ntorga.com/the-clean-coder-golden-rules/);
+- Follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification for every commit message;
+- Obtain approval from two developers before merging. If you lack merge permissions, the second reviewer can complete the merge for you;
+
+By following these guidelines, you help maintain project quality and consistency while making contributions valuable to the community.

docs/DEVELOPMENT.md

@@ -0,0 +1,132 @@
+# Development
+
+Before contributing to the project, please read the [Contributing](docs/CONTRIBUTING.md) document. It contains important information about the project's guidelines and expectations.
+
+The public roadmap for Infinite OS is available [here](https://github.com/orgs/goinfinite/projects/9). You may create issues or pull requests to contribute to the project.
+
+This project uses Clean Architecture, DDD, TDD, CQRS, Object Calisthenics, etc. Understand how these concepts works before proceeding is advised.
+
+## Building
+
+### Simple Build
+
+To build the project, run the command below. It takes two minutes to build the project at first. After that, it takes less than 10 seconds to build.
+
+```
+podman build -t os:latest .
+```
+
+To run the project you may use the following command:
+
+```
+podman run --name os --env 'PRIMARY_VHOST=goinfinite.local' --rm -p 1618:1618 -it os:latest
+```
+
+When testing, consider publishing port 80 and 443 to the host so that you don't need to use a reverse proxy. You should also consider using `--env 'LOG_LEVEL=debug'` to increase the log verbosity.
+
+## Development Build
+
+When developing the project, you may want to use a script to automate the build process. The `dev-build.sh` script is available in the root of the project and it will take care of all the steps needed to build and run the container.
+
+To run the script you can simply use `bash dev-build.sh` (bash may be replaced by zsh or similar). By default, the script will expose the port 1618 to the host which is used by the API and the dashboard.
+
+- If you pass the `http` argument, it will also expose the ports 80 and 443 to the host;
+- If you pass the `ols` argument, it will expose port 7080 (used by OpenLiteSpeed admin);
+- If you pass the `no-cache` argument, it will remove the image cache and rebuild the image from scratch;
+
+The script will also create a `dev` account with the password `123456` so you can access the dashboard.
+
+When you need to stop the container, just CTRL+C to stop and remove it. If you don't want to remove it, just ditch the `--rm` flag from the `podman run` command in the script.
+
+If you look closely at the script, you'll see that it mounts the project's `bin` directory to the container `/infinite/bin` path. This is done to allow the container to access the binary file generated by Air on the host. The script then replace the binary file that comes with the container with the one on the `/bin` directory.
+
+With this approach you don't need to rebuild the container every time you change the code. Although sometimes you may want to restart the container to apply some changes, specially when changing the dependencies or system configurations. In this case, just hit CTRL+C to stop the container and run the script again.
+
+**Notes:**
+
+1. You must run the script from the project's root directory;
+2. Until Echo v4.13.0 is released, you'll need to refresh the browser page during development to see the changes in the dashboard as we're not able to use the `DEV_MODE` auto refresh websocket trick for now. To understand how this trick used to work, check the UI router and main layout files.
+
+## Unit Testing
+
+Infinite OS commands can harm your system, so it's important to run the unit tests in a proper container:
+
+```
+podman build -t os-unit-test:latest -f Containerfile.test .
+podman run --rm -it os-unit-test:latest
+```
+
+Make sure you have a `.env` file in the root of the git directory before running the tests.
+
+Some tests can run in your local machine, although it's not recommended. However, if you to give it a go, make sure to create the `/infinite/` directory before running the tests:
+
+```
+sudo mkdir /infinite
+sudo chown $(whoami):$(whoami) /infinite
+```
+
+## Web UIs
+
+This project web UI is based on a combo [Templ](https://templ.guide/) + [Alpine.js](https://alpinejs.dev/) + [HTMX](https://htmx.org/docs/).
+
+To understand the entire conceptual and theoretical foundation behind using these technologies to create a new frontend architecture, [access this article](https://ntorga.com/full-stack-go-app-with-htmx-and-alpinejs/). However, to grasp the practical basis of how to apply this new architecture, [refer to the proof of concept](https://github.com/ntorga/clean-ddd-full-stack-go-poc) used to develop it.
+
+For the interface code to be read and rendered by Go, we need to convert all `.templ` files into `.go` files. To do this, run the following command at the root of the application:
+
+```
+templ generate -path src/presentation/api
+```
+
+It is important that this is done before using Air to create the binary; otherwise, the Web UI will not be embedded, and you will not be able to use it.
+
+**NOTE:** If you are using the `dev-build.sh` script, you don't need to run the `templ generate` command (or Air for that matter) since the script will take care of everything for you.
+
+## Marketplace and Services Catalog
+
+The marketplace and services catalog are not part of this project. You can find their repositories at [goinfinite/os-services](https://github.com/goinfinite/os-services) and [goinfinite/os-marketplace](https://github.com/goinfinite/os-marketplace). Both are managed by Infinite DevOps team directly and their items manifests are based on JSON and YAML files. Read the instructions in their respective repositories to understand how to use, extend and contribute to them.
+
+## VSCode Extensions
+
+The following extensions are highly encouraged to be used during development:
+
+```
+EditorConfig.EditorConfig
+GitHub.copilot
+GitHub.vscode-pull-request-github
+esbenp.prettier-vscode
+foxundermoon.shell-format
+golang.go
+hbenl.vscode-test-explorer
+ms-vscode.test-adapter-converter
+redhat.vscode-yaml
+streetsidesoftware.code-spell-checker
+timonwong.shellcheck
+```
+
+## REST API
+
+### Authentication
+
+The API accepts two types of tokens and uses the standard "Authorization: Bearer \<token\>" header:
+
+- **sessionToken**: is a JWT, used for dashboard access and generated with the account login credentials. The token contains the accountId, IP address and expiration date. It expires in 3 hours and only the IP address used on the token generation is allowed to use it.
+
+- **accountApiKey**: is a token meant for M2M communication. The token is a _AES-256-CTR-Encrypted-Base64-Encoded_ string, but only the SHA3-256 hash of the key is stored in the server. The accountId is retrieved during key decoding, thus you don't need to provide it. The token never expires, but the user can update it at any time.
+
+### OpenApi // Swagger
+
+To generate the swagger documentation, you must use the following command:
+
+```
+swag init -g src/presentation/api/api.go -o src/presentation/api/docs
+```
+
+The annotations are in the controller files. The reference file can be found [here](https://github.com/swaggo/swag#attribute).
+
+When the project is running, you can access the documentation at [`https://localhost:1618/api/swagger/`](https://localhost:1618/api/swagger/) (or the IP address of your host machine if you're not using localhost).
+
+## Dev Utils
+
+The `src/devUtils` folder is not a Clean Architecture layer, it's there to help you during development. You can add any file you want there, but it's not recommended to add any file that is not related to development since the code there is meant to be ignored by the build process.
+
+For instance there you'll find a `testHelpers.go` file that is used to read the `.env` during tests.

docs/SECURITY.md

@@ -0,0 +1,37 @@
+# Security Policies
+
+## Supported Versions
+
+We provide security updates only for the latest version of Infinite OS. In case of a critical vulnerability, we will not backport the fix to the previous version. We recommend that you redeploy your application with the latest version available of Infinite OS. That way you will always have the latest security updates and features from Infinite OS and also the underlying operating system.
+
+## Reporting a Vulnerability
+
+We take the security at Infinite very seriously. If you believe you've found a security vulnerability, we encourage you to inform us responsibly.
+
+**Do not report security vulnerabilities through public GitHub issues.**
+
+Instead, please send an email to us at eng _at_ goinfinite.net (do not use this email for support questions). You should receive a response within 48 hours. If for some reason you do not, please follow up via email to ensure we received your original message.
+
+To help us better understand the nature and scope of the potential issue, please describe as much as you can about the vulnerability:
+
+- Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.);
+- Full paths of source file(s) related to the manifestation of the issue;
+- The location of the affected source code (tag/branch/commit or direct URL);
+- Any special configuration required to reproduce the issue;
+- Step-by-step instructions to reproduce the issue;
+- Proof-of-concept or exploit code;
+- Impact of the issue, including how an attacker might exploit the issue.
+
+This information will help us triage your report more quickly.
+
+Our security team will acknowledge your email within 48 hours, and you'll receive a more detailed response to your email within 48 hours indicating the next steps in handling your report.
+
+## Policy
+
+If you follow these guidelines when reporting an issue to us:
+
+- We will acknowledge your report & provide an estimated timeframe for a fix;
+- We will notify you when the issue is resolved;
+- We will not take legal action against or suspend or terminate your access to the project.
+
+We strive to keep all our users safe and will make our best effort to promptly fix any security issue.