Skip to content

Latest commit

 

History

History
238 lines (146 loc) · 7.68 KB

development-setup.md

File metadata and controls

238 lines (146 loc) · 7.68 KB
Raw

Development Setup

This guide assumes you have the following commands installed and available in your environment:

  • docker
  • go (>= 1.21)
  • node (>= 18)
  • make

Note: While GoAlert requires Go 1.23 for development, starting from Go 1.21, Go will automatically download and use the correct toolchain version specified in the project (go 1.23 in go.mod). Therefore, Go 1.21 is the minimum version you need to have installed, but the latest version is recommended.

Quick Start

To start the development environment, ensure that Docker is running and execute:

make start

Once the server is up, you can access the GoAlert UI at http://localhost:3030. Log in using the default credentials:

  • Username: admin
  • Password: admin123

Security Note: The default credentials are intended for development purposes only. If your development environment is accessible over a network, it's recommended to change the password to prevent unauthorized access.

In development mode, you'll see a Dev item in the navigation bar. This allows you to configure and access additional integrations such as Prometheus and email messages.

VSCode Configuration

If you are using Visual Studio Code (VSCode), you can run:

make vscode

This command installs the Yarn SDK for VSCode, ensuring compatibility with the Yarn Plug'n'Play (PnP) setup used by GoAlert. By default, VSCode extensions expect dependencies to be in node_modules, but Yarn PnP uses a different mechanism for dependency resolution. Running make vscode resolves this by configuring VSCode to work with Yarn PnP.

External Traffic

To test features that require external callbacks (e.g., webhooks from third-party services), you'll need a publicly accessible URL that points to your local development server.

Start the development environment with the PUBLIC_URL environment variable set:

make start PUBLIC_URL=https://localdev.example.com

Using ngrok to Expose Your Local Server

To expose your local server to the internet, you can use a tool like ngrok. First, ensure ngrok is installed on your system. Then, add the following line to your Procfile.local:

ngrok: ngrok http 3030

This configuration starts ngrok automatically when you run make start, creating a public URL that tunnels to your local server. The public URL provided by ngrok will look something like https://abcd1234.ngrok.io.

Database (PostgreSQL)

GoAlert is built and tested against PostgreSQL 13. While versions 11 and newer should work, using PostgreSQL 13 is recommended for compatibility.

Starting PostgreSQL

When you run make start, GoAlert automatically starts a PostgreSQL instance using Docker. If you need to start it manually, you can run:

make postgres

Connecting to the Database

You can connect to the local database using psql or a GUI tool like pgAdmin or TablePlus. Use the following connection details:

  • Host: localhost
  • Port: 5432
  • Database: goalert
  • User: goalert
  • Password: (leave blank)

Alternatively, you can use the connection URL:

postgres://goalert@localhost:5432/goalert

Database Management

To reset or regenerate the database (e.g., to resolve migration errors or test with a different dataset size), run:

make regendb

Warning: This command will erase any existing data in the database and generate a fresh schema with sample data.

Scaling Sample Data with SIZE

You can control the amount of sample data generated by specifying the SIZE parameter. For example:

make regendb SIZE=10

The SIZE parameter scales the amount of random data inserted into the database. A higher number creates more data, which can be useful for testing scalability and performance.

This command also creates an admin user with the credentials admin/admin123.

Manual Database Configuration

If you have PostgreSQL running locally and prefer not to use Docker, you can manually set up the goalert role:

CREATE ROLE goalert WITH LOGIN SUPERUSER;

Note: The development user must have superuser privileges to enable the pgcrypto extension using CREATE EXTENSION.

Alternatively, if you prefer not to grant superuser privileges, you can manually enable the pgcrypto extension in your database:

CREATE EXTENSION IF NOT EXISTS pgcrypto WITH SCHEMA public;

Ensure that the user goalert has the necessary permissions to interact with the database schema.

Testing

Playwright Tests

GoAlert uses Playwright for automated browser testing. You can start Playwright in one of the following modes:

  • Start the Playwright UI:

    make playwright-ui

    This command opens the Playwright Test Runner UI, allowing you to run and debug tests interactively.

  • Run All Tests in Headless Mode:

    make playwright-run

    This command runs all Playwright tests in headless mode, suitable for continuous integration pipelines or automated testing scenarios.

Running Smoke Tests

A suite of functional and behavioral tests are maintained for the backend code. These tests cover various APIs and behaviors of the GoAlert server component.

Run the full suite of smoke tests with:

make test-smoke

Note: These tests require that PostgreSQL is running.

Running Unit Tests

Go Unit Tests

All Go unit tests can be run with:

make test-unit

To run tests for a specific package or file, you can use the go test command directly:

go test ./path/to/package -v

UI Unit Tests

UI unit tests are located alongside the components they test, with the same filename appended with .test.js.

To run all UI unit tests independently of the Go unit tests, use:

make jest

To run tests in watch mode, which re-runs tests when files change, use:

make jest JEST_ARGS=--watch

To run a specific test file:

make jest JEST_ARGS=path/to/your.test.js

Generating Test Coverage Reports

To generate test coverage reports for UI tests, run:

make jest JEST_ARGS=--coverage

Additional Information

Environment Variables

Some environment variables can affect the behavior of the development environment:

  • PUBLIC_URL: Sets the publicly accessible URL for your local server. Useful for testing integrations that require callbacks from external services.
  • SIZE: Controls the amount of sample data generated during make regendb.

Prerequisites

Ensure that your system meets the following requirements:

Troubleshooting

Common Issues

  • Docker Not Running: Ensure that Docker Desktop or the Docker daemon is running before executing make start.
  • Port Conflicts: If you receive errors about ports already in use, ensure that no other services are running on the required ports (e.g., 3030 for the GoAlert server).

Getting Help

If you encounter issues not covered in this guide, consider reaching out via: