Soundgo

Soundgo is a REST API for a simple audio hosting service. It provides a platform for users to manage and interact with audio content.

Technologies Used

• go
• openAPI
• PostgreSQL
• Grafana
• Loki
• Docker
• Hurl
• redocly
• ogen
• pgx
• Goose
• jwx

Getting Started

The project is heavily dockerized, making it easy to set up and run the development environment.

To start the development environment, use the following command:

make start-env

This command will start a development environment that includes all necessary dependencies:

• A bash shell (accessible using make shell)
• A Go binary
• A migrations runner (goose)
• Hurl (for e2e tests)
• Redocly-CLI (for autogenerated REST API docs)
• A debugger (delve)

These tools are pre-configured and ready to use, allowing you to start developing and testing immediately.

Environment Variables

The project requires several environment variables to be set for proper configuration. Create a .env file in the root directory of the project with the following variables:

# Database Configuration
DB_USER=
DB_PORT=
DB_PASSWORD=
DB_NAME=
DB_HOST=

# Test Database Configuration
TEST_DB_USER=
TEST_DB_PORT=
TEST_DB_PASSWORD=
TEST_DB_NAME=
TEST_DB_HOST=

# Goose Migration Tool Configuration
GOOSE_DRIVER=
GOOSE_DBSTRING=
TEST_GOOSE_DBSTRING=

# JWT Configuration
JWT_KEY=

# Server Configuration
PORT=
TEST_PORT=
HOST=
TEST_HOST=

# File Storage Configuration
AUDIOS_PATH=

# Play Count Save Interval (in seconds)
PLAY_COUNT_SAVE_INTERVAL=
TEST_PLAY_COUNT_SAVE_INTERVAL=

Fill in these variables with your own values according to your specific setup and requirements. It's crucial to keep sensitive information, such as database passwords and JWT keys, secure and never commit them to version control.

Important notes:

1. Use strong, unique passwords for database access.
2. Generate a secure random string for the JWT_KEY.
3. Ensure the AUDIOS_PATH points to a directory with appropriate read/write permissions.
4. Adjust the PORT and HOST values based on your deployment environment.
5. Set appropriate intervals for PLAY_COUNT_SAVE_INTERVAL based on your application's needs.

Running Tests

The project includes different types of tests to ensure code quality and functionality. You can run these tests using the following commands:

Unit and Integration Tests

To run unit and integration tests, use:

make test

This command will execute all unit tests and integration tests for the project.

End-to-End (E2E) Tests

For running end-to-end tests, use:

make e2e-tests

This command will perform all end-to-end tests, simulating real-world usage scenarios of the API.

Database Migrations

Soundgo uses database migrations to manage the database schema. We use the Goose migration tool for this purpose.

Running Migrations

To apply all pending migrations to your database, use the following command:

make run-migrations

This command will update your database to the latest schema version.

Creating New Migrations

To create a new migration, use the following command:

make create-migration name=<migration_name>

Replace <migration_name> with a descriptive name for your migration. For example:

make create-migration name=users_table

This command will generate a new .sql file in the ./migrations directory. The file will be named with a timestamp and the migration name you provided.

After creating a migration:

1. Open the newly created .sql file in the ./migrations directory.
2. Add your SQL commands for the migration in this file. Typically, you'll include both "up" (apply changes) and "down" (revert changes) sections.
3. After editing the migration file, you can apply it using the make run-migrations command.

Starting the Server

Once you have set up your environment variables and started the development environment, you can launch the HTTP server using the following command:

make dev-server

This command will start the Soundgo API server in development mode. The server will be accessible at the host and port specified in your environment variables (HOST and PORT).

After running this command, your API should be up and running, ready to accept requests. You can now use tools like cURL, Postman, or your web browser to interact with the API endpoints.

Remember to ensure that all required services (like the database) are running and properly configured before starting the server.

For any issues or unexpected behavior, check the console output for error messages or logs that might help in troubleshooting.

Debugging

Soundgo provides a convenient way to debug the application using Delve, a powerful debugger for Go.

To start a debug session, use the following command:

make debug

This command will start a bash shell where you'll have access to dlv, the Delve debugger. Within this debug environment, you have two main options for debugging:

1. Debugging Tests:

   dlv test
   

2. Debugging the Entire Application:

   dlv debug ./cmd/main/*.go
   

For a comprehensive guide on using Delve, please refer to the official documentation: Delve Documentation

OpenAPI Specification and Documentation

Soundgo uses OpenAPI specification for API documentation and code generation. We use ogen to generate code from the OpenAPI spec.

Updating OpenAPI Specification

When you add or modify the OpenAPI specification, you need to regenerate the code. Use the following command:

make generate-openapi

This command will update the generated code based on the current OpenAPI specification. Make sure to run this command and commit the changes whenever you update the API spec.

Previewing API Documentation

To preview the REST API documentation, including available requests and request examples, use:

make preview-docs

This command starts a server listening on port 8080. You can then access the API documentation in your web browser.

The documentation includes:

• Available endpoints
• Request/response schemas
• Example requests
• Authentication requirements
• Any additional API details specified in the OpenAPI spec

Note: The preview server is intended for development and internal use

Monitoring and Logging

Soundgo includes a Grafana dashboard for monitoring and visualizing logs-based metrics. The setup uses Promtail to collect logs and sends them to Loki, which is then visualized in Grafana.

Setting Up the Dashboard

To set up and run the Grafana dashboard:

1. Navigate to the Grafana directory:

   cd ./grafana
   

2. Start the Grafana stack:

   docker compose up
   

This command will start Grafana, Loki, and Promtail services.

Accessing the Grafana UI

Once the services are up and running:

• The Grafana UI is available at http://localhost:3000

Dashboard Features

The Grafana dashboard provides:

• Visualization of logs-based metrics
• Real-time monitoring of application performance
• Customizable panels and graphs
• Ability to set up alerts based on log patterns or metrics

Refer to the Grafana documentation for more advanced configurations and usage.