Installation Guide

This guide will walk you through setting up the go-clean-arch project on your local machine for development and testing. The project uses Docker and Docker Compose to simplify the setup of the database and application environment.

Prerequisites

Before you begin, ensure you have the following tools installed on your system:

  • Go: Version 1.20 or later. Installation Guide
  • Docker: To run the application and database in containers. Installation Guide
  • Docker Compose: To orchestrate the multi-container setup. Installation Guide
  • Make: To use the convenient commands defined in the Makefile.
  • Git: To clone the repository.

Step 1: Clone the Repository

First, clone the project from GitHub to your local workspace.

git clone https://github.com/bxcodec/go-clean-arch.git
cd go-clean-arch

Step 2: Configure Environment Variables

The application uses environment variables for configuration. A sample configuration file example.env is provided. Copy it to create your own .env file.

cp example.env .env

The default values in .env are configured to work with the Docker Compose setup. You can review the variables in this file, but no changes are necessary to get started.

For a detailed explanation of all configuration options, see the Configuration page.

Step 3: Start the Application Environment

The Makefile provides a simple command to build and start all the necessary services, including the MySQL database and the Go application.

The make up command performs the following actions:

  1. Starts a MySQL container using docker-compose.
  2. The MySQL container automatically initializes the article database using the article.sql schema and data file.
  3. Starts the air live-reloader, which watches for file changes, recompiles, and restarts the Go application automatically.

Run the following command from the project root:

make up

You will see output from Docker Compose as it pulls images and starts the containers, followed by logs from the air process indicating that the Go application is running.

❯ make up
[... Docker Compose output ...]

  __    _   __  __
 /\ \  /\ \/\ \/\ \ 
 \ \ \/\ \ \ \ \_\ \ 
  \ \__\ \_\ \_\_\_\ 
   \/__/\/_/\/_/\/_/   

- watching files... 
- building... 
- running...

Step 4: Verify the Installation

Once the application is running, it will be accessible at http://localhost:9090. You can verify that everything is working by sending a request to the /articles endpoint using curl or any other HTTP client.

curl localhost:9090/articles

You should receive a JSON response containing a list of articles, similar to this:

[
    {
        "id": 1,
        "title": "Makan Ayam",
        "content": "<p>But I must explain to you...",
        "author": {
            "id": 1,
            "name": "Iman Tumorang",
            "created_at": "2017-05-18T13:50:19Z",
            "updated_at": "2017-05-18T13:50:19Z"
        },
        "updated_at": "2017-05-18T13:50:19Z",
        "created_at": "2017-05-18T13:50:19Z"
    },
    ...
]

Congratulations! You have successfully set up and run the go-clean-arch project. To learn more about how to interact with the API, check out the Quick Start guide and the API Reference.