Skip to content

Latest commit

 

History

History
159 lines (108 loc) · 5.95 KB

CONTRIBUTING.md

File metadata and controls

159 lines (108 loc) · 5.95 KB
Raw

Contributing to Phase 🫡

Thanks for taking the time to contribute!

We welcome any contributions to Phase, big or small.

Minimum System Requirements 🦕

To run Phase locally, ensure your system meets the following minimum requirements:

  • System !=🥔
  • RAM: >= 8GB (preferably 16GB)

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 [email protected]

For more information, see: SECURITY.md

Deciding What to Work On 🏋️

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 🏗️

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.

Licensing ⚖️

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.

Get Phase running locally 👩‍💻

Dev Server with Hot Reload

  1. Create a .env.dev file using:

    cp .env.dev.example .env.dev

  2. Add at least one of the available OAuth provider credentials in your .env.dev. Follow the Phase Docs.

  3. Install the dependencies:

    docker compose -f dev-docker-compose.yml build

  4. Start the containers in dev mode using:

    docker compose -f dev-docker-compose.yml up

  5. The Console is now running at https://localhost with HMR (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:

    cp .env.example .env

  2. Add at least one of the available OAuth provider credentials in your .env. Follow the Phase Docs.

  3. Build the image locally with:

    docker compose -f staging-docker-compose.yml build

  4. Start the Phase Console with:

    docker compose -f staging-docker-compose.yml up -d

  5. The Console is now running at https://localhost with 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 the Phase CLI

  1. Install the CLI:

  2. Create a personal access token in the Phase Console:

  3. Log in via the CLI:

    • Run the following command: 
      phase auth --mode token
    • Select "🛠️ Self Hosted" from the dropdown
    • For the Phase Console host URL, enter: http://localhost (Note: Use http instead of https to avoid SSL certificate errors with self-signed certificates)
    • Enter your email
    • Copy and paste your Phase personal access token you created in the Phase Console

For more information on phase auth, see: https://docs.phase.dev/cli/commands#auth

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:
    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
# ...

  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

  4. CLI Errors

    • If you encounter any CLI errors, run the CLI in debug mode to get more information: 
      PHASE_DEBUG=True phase <your sub-command>

Need help? Join our Slack

Thank you for contributing to Phase!