diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 825f11c23..17995d454 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,60 +1,131 @@ -# Contributing to Phase +# Contributing to Phase ๐Ÿซก -Thanks for taking the time to contribute! โค๏ธ +Thanks for taking the time to contribute! We welcome any contributions to Phase, big or small. -## Community +## Minimum System Requirements ๐Ÿฆ• -It's the early days of Phase and we're working hard to build an awesome, inclusive community. +To run Phase locally, ensure your system meets the following minimum requirements: +- **System** !=๐Ÿฅ” +- **RAM:** >= 8GB (preferably 16GB) -## Bugs and issues -Bug reports help make Phase a better experience for everyone. When you report a bug, a template will be created automatically containing information we'd like to know. +## Prerequisites ๐Ÿ› ๏ธ + +Before setting up your development environment, ensure you have the following prerequisites installed ๐Ÿณ: +- Docker +- Docker Compose +- Git + +## Bugs and Issues ๐Ÿงถ + +Bug reports help make Phase a better experience for everyone. When you report a bug, a template will be created automatically containing the information we'd like to know. Before raising a new issue, please search existing ones to make sure you're not creating a duplicate. -**If the issue is related to security, please email us directly at security@phase.dev** +**If the issue is related to security, please email us directly at `security@phase.dev`** -For more information see: [SECURITY.md](/SECURITY.md) +For more information, see: [SECURITY.md](/SECURITY.md) -## Deciding what to work on +## Deciding What to Work On ๐Ÿ‹๏ธ -You can start by browsing through our list of issues or adding your own that improves on the platform experience. Once you've decided on an issue, leave a comment and wait to get approved; this helps avoid multiple people working on the same issue. +You can start by browsing through our list of issues or adding your own that suggests a new feature or improves the platform experience. Once you've decided on an issue, leave a comment and wait to get approved; this helps avoid multiple people working on the same issue. If you're ever in doubt about whether or not a proposed feature aligns with Phase as a whole, feel free to raise an issue about it and we'll get back to you promptly. -## Writing and submitting code +## Writing and Submitting Code ๐Ÿ—๏ธ -Anyone can contribute code to Phase. To get started, check out the local development guide, make your changes, and submit a pull request to the main repository. When committing code, please try and use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/). +Anyone can contribute code to Phase. To get started, check out the local development guide, make your changes, and submit a pull request to the main repository. When committing code, please try to use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/). -## Licensing +## Licensing โš–๏ธ -Most of Phase's code is under the MIT license, though some paid feature restrictions are covered by a proprietary license. +Most of Phase's code is under the MIT license, though some paid feature restrictions may be covered by a proprietary license. -Any third party components incorporated into our code are licensed under the original license provided by the applicable component owner. +Any third-party components incorporated into our code are licensed under the original license provided by the applicable component owner. -## Setup local development environment -### Dev server with hot reload -1. Create a **.env.dev** file using - ``` +## Get Phase running locally ๐Ÿ‘ฉโ€๐Ÿ’ป + +### Dev Server with Hot Reload + +1. Create a **.env.dev** file using: + ```bash cp .env.dev.example .env.dev ``` -2. Add atleast one OAuth provider in your **.env.dev**. Follow the [docs](https://docs.phase.dev/self-hosting/configuration/envars) -3. Verify that **dev-docker-compose.yml** file is populated with the correct environment variables by running + +2. Add at least one of the available OAuth provider credentials in your **.env.dev**. Follow the [Phase Docs](https://docs.phase.dev/self-hosting/configuration/envars#single-sign-on-sso). + +3. Install the dependencies: + ```bash + docker compose -f dev-docker-compose.yml build + ``` + +4. Start the containers in dev mode using: + ```bash + docker compose -f dev-docker-compose.yml up + ``` + +5. The Console is now running at with [HMR (Hot Module Replacement)](https://webpack.js.org/concepts/hot-module-replacement) and a self-signed certificate. + + >**Note:** Your browser might warn you about the self-signed certificate. You can safely accept the certificate and proceed. + +### Set Up a Staging Environment + +1. Create a **.env** file using: + ```bash + cp .env.example .env ``` - docker compose -f dev-docker-compose.yml --env-file .env.dev config + +2. Add at least one of the available OAuth provider credentials in your **.env**. Follow the [Phase Docs](https://docs.phase.dev/self-hosting/configuration/envars#single-sign-on-sso). + +3. Build the image locally with: + ```bash + docker compose -f staging-docker-compose.yml build ``` -4. Start the containers using + +4. Start the Phase Console with: + ```bash + docker compose -f staging-docker-compose.yml up -d ``` - docker-compose -f dev-docker-compose.yml --env-file .env.dev up + +5. The Console is now running at with a self-signed certificate. + + >**Note:** Your browser might warn you about the self-signed certificate. You can safely accept the certificate and proceed. + +### Common Problems / Issues ๐Ÿ—ฟ + +1. **Certificate Errors** + - Caused by a self-signed certificate. + - Solved by adding a valid certificate to the NGINX config in `nginx/default.conf`. + - Use a reverse proxy that will add a valid certificate like `cloudflared` or `tailscale serve`. + +2. **NGINX 503 / Timeouts / Hot Reloading Not Working** + - Caused by a slow system. + - Please check how much leftover RAM you have after starting all the containers. + - Additionally, for slower systems facing timeout issues, try increasing NGINX proxy timeouts by adding the following code snippet: + + ```nginx + server { + listen 80; + listen 443 ssl http2; + + ssl_certificate /etc/nginx/ssl/nginx.crt; + ssl_certificate_key /etc/nginx/ssl/nginx.key; + + # Increase the timeout to 3 minutes + proxy_connect_timeout 180s; + proxy_send_timeout 180s; + proxy_read_timeout 180s; + } + + # Rest of your config + # ... ``` -5. The Console is now running at with [HMR(Hot Module Replacement)](https://webpack.js.org/concepts/hot-module-replacement) and a self-signed certificate. - >**Note : Your browser might warn you about the self-signed certificate. You can safely accept the certificate and proceed. -### Staging env to test production builds +3. **Having Issues Signing In (Redirected Back to the Phase Console Log-In Screen Even After OAuth Authentication)** + - Please make sure the OAuth credentials and the callback URL are correct and as described in the docs: [Phase Docs](https://docs.phase.dev/self-hosting/configuration/envars#single-sign-on-sso) + +Need help? +[Join our Slack](https://slack.phase.dev) -1. Set up a `.env` file with `cp .env.example` and add atleast one OAuth provider. View the [docs](https://docs.phase.dev/self-hosting/configuration/envars) for more info. -2. Build the image locally with `docker-compose -f staging-docker-compose.yml build` -3. Bring docker compose up with `docker-compose -f staging-docker-compose.yml up` -4. The Console is now running at `https://localhost`. +Thank you for contributing to Phase! \ No newline at end of file diff --git a/README.md b/README.md index 95ae0cf5f..2e4cfc2cb 100644 --- a/README.md +++ b/README.md @@ -13,29 +13,29 @@ --- -[Phase](https://phase.dev) is an all-in-one platform for developers to securely create, manage and deploy application secrets across local development ๐Ÿ’ป, CI tools ๐Ÿ”จ, and cloud โ˜๏ธ infrastructure. +Open source platform for fast-moving engineering teams to secure and deploy application secrets โ€” from development to production. -An open source and developer-friendly alternative to **HashiCorp Vault** and **AWS Secrets Manager** that works with your whole team ๐Ÿง‘โ€๐Ÿ’ป. +A developer-friendly alternative to **HashiCorp Vault** and **AWS Secrets Manager** that works with your whole team ๐Ÿง‘โ€๐Ÿ’ป. --- # Phase Console - -Phase Console +https://github.com/user-attachments/assets/160c721d-a941-440a-bc42-afd419c1df18 | | **Features** | | --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -| ๐Ÿ“ˆ | **[Phase Console](https://console.phase.dev)**: Dashboard for seamlessly creating, managing, rotating secrets and environment variables | -| โŒจ๏ธ | **[CLI](https://github.com/phasehq/cli)**: Import existing secrets from `.env` files, encrypt them and securely inject them in your application at runtime | -| ๐Ÿคซ | **[Secret management](https://docs.phase.dev/console/apps)**: Secret Diffs, version control and Point-in-time Recovery | -| ๐Ÿ™‹ | **[RBAC](https://docs.phase.dev/console/users#user-roles)**: Fine-grained, role-based and cryptographic access control, per application, per environment. | -| ๐Ÿ”Œ | **[Integrations](https://docs.phase.dev/#integrate-phase)**: Automatically sync secrets to GitHub, Cloudflare Pages, AWS Secrets Manager etc. | -| ![Kubernets](img/kubernetes.svg) | **[Kubernetes](https://docs.phase.dev/integrations/platforms/kubernetes)**: Automatically deploy secrets to your Kubernetes Cluster with End-to-End encryption via Phase Secrets Operator | +| ๐Ÿ“ˆ | **[Phase Console](https://console.phase.dev)**: Dashboard for seamlessly creating, managing, rotating secrets, and environment variables | +| โŒจ๏ธ | **[CLI](https://github.com/phasehq/cli)**: Import existing secrets from `.env` files, encrypt them, and securely inject them in your application at runtime | +| ๐Ÿคซ | **[Secret management](https://docs.phase.dev/console/apps)**: Secret Diffs, version control, and recovery | +| ๐Ÿ™‹ | **[RBAC](https://docs.phase.dev/console/users#user-roles)**: Fine-grained, role-based, and cryptographic access control, per application, per environment. | +| ๐Ÿ”Œ | **[Integrations](https://docs.phase.dev/#integrate-phase)**: Automatically sync secrets to GitHub, Cloudflare Pages, GitLab CI, Railway, AWS Secrets Manager, etc. | +| ![Kubernetes](img/kubernetes.svg) | **[Kubernetes](https://docs.phase.dev/integrations/platforms/kubernetes)**: Automatically deploy secrets to your Kubernetes Cluster with End-to-End encryption via Phase Secrets Operator | | โ›“๏ธ | **[Secret referencing & overrides](https://docs.phase.dev/console/secrets)**: Create personal secrets. Inherit values from other secrets | +| ๐ŸŒ | **[REST API](https://docs.phase.dev/public-api/secrets#get-secrets)**: Access and manage secrets programmatically | +| ๐Ÿ“ฆ | **[SDKs](https://docs.phase.dev/sdks)**: SDKs for integrating Phase with various programming languages and frameworks | ๐Ÿฅก | **[Self Hosting](https://docs.phase.dev)**: Run Phase on your own infrastructure | -| ๐Ÿ”‘ | **[Service Tokens](https://docs.phase.dev/console/tokens#service-tokens)**: Authenticate CI runners, build tools and production environment with granular scope | -| ๐Ÿ” | **[Audit Logs]()**: Complete visibility into every change and access event | +| ๐Ÿ” | **[Audit Logs]()**: Complete visibility into every change and access event | | | [Explore Phase Console](https://docs.phase.dev/console) @@ -87,6 +87,7 @@ Commands: users whoami ๐Ÿ™‹ See details of the current user users logout ๐Ÿƒ Logout from phase-cli users keyring ๐Ÿ” Display information about the Phase keyring + docs ๐Ÿ“– Open the Phase CLI Docs in your browser console ๐Ÿ–ฅ๏ธ Open the Phase Console in your browser update ๐Ÿ†™ Update the Phase CLI to the latest version ``` @@ -103,6 +104,8 @@ Check out the [Quickstart](https://docs.phase.dev/quickstart) Guides The quickest and most reliable way to get started is by signing up on the [Phase Console](https://console.phase.dev/). +### Self-host Phase + | | **Deploy Phase Console on your infrastructure** | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | |![Docker](img/docker.svg) | [Docker Compose](https://docs.phase.dev/self-hosting/docker-compose) | @@ -116,7 +119,7 @@ The quickest and most reliable way to get started is by signing up on the [Phase ### SDKs -- [JavaScript Browser](https://github.com/phasehq/client-js-sdk) +- [Golang](https://docs.phase.dev/sdks/go) - [Node.js](https://github.com/phasehq/node-sdk) - [Python](https://github.com/phasehq/python-sdk) diff --git a/img/console-ui.mp4 b/img/console-ui.mp4 new file mode 100644 index 000000000..8cfa30526 Binary files /dev/null and b/img/console-ui.mp4 differ diff --git a/img/console-ui.webp b/img/console-ui.webp new file mode 100644 index 000000000..5def4b57b Binary files /dev/null and b/img/console-ui.webp differ