Creating your first project

Welcome to this hands-on tutorial where you'll learn how to build a production-ready RESTful API using the Codoworks Go boilerplate. By the end of this tutorial, you'll have a fully functional phonebook service that demonstrates best practices in Go API development.

Naming your project

Coming up with a name for a new project can be a very challenging and time-consuming task. For this tutorial, we'll use phonebook as our project name - simple and descriptive.

Let's start by downloading the source code. Open up your terminal and run:

git clone git@github.com:codoworks/go-boilerplate.git phonebook
cd phonebook

Note: If you don't have SSH access to GitHub, you can use HTTPS instead:

Next, you'll need to change all the import paths to match your new project name. All import paths in the boilerplate point to github.com/codoworks/go-boilerplate by default. You can change it using the same format of github.com/<username>/<project-name>.

You can do that in one of two ways:

Option 1: Using Terminal Commands

LC_ALL=C find ./ -type f -exec sed -i '' -e 's#github.com/codoworks/go-boilerplate#github.com/codoworks/phonebook#g' {} \;

Option 2: Using VS Code

1. Press Cmd+Shift+F (Mac) or Ctrl+Shift+F (Windows/Linux) to open the search panel
2. Enter github.com/codoworks/go-boilerplate in the search field
3. Enter github.com/codoworks/phonebook in the replace field
4. Click "Replace All"

Download dependencies

Go's package management is straightforward. Run:

go get

Environment setup

The boilerplate comes with predefined environment values, allowing for zero-configuration setup. You can view the current environment configuration using:

go run . info env

which should print out something like

file '.env' not found
attempting to read env vars ...
╭──────────────────────────────────────╮
│ Environment                          │
├──────────────────────────┬───────────┤
│ ENV                      │ VALUE     │
├──────────────────────────┼───────────┤
│ DISABLE_FEATURES         │ []        │
│ HOST                     │ 0.0.0.0   │
│ PROTECTED_API_PORT       │ 8080      │
│ PUBLIC_API_PORT          │ 8081      │
│ HIDDEN_API_PORT          │ 8079      │
│ LOG_LEVEL                │ warn      │
│ REQUEST_TIMEOUT_DURATION │ 60        │
│ WATCHER_SLEEP_INTERVAL   │ 5000      │
│ DB_HOST                  │           │
│ DB_PORT                  │           │
│ DB_USER                  │           │
│ DB_PASSWORD              │           │
│ DB_NAME                  │ sqlite.db │
│ DB_TIMEZONE              │ Etc/GMT   │
│ DB_PLATFORM              │ sqlite    │
│ DB_SSL_MODE              │ disable   │
│ KRATOS_PUBLIC_SERVICE    │           │
│ KRATOS_ADMIN_SERVICE     │           │
│ KETO_READ_SERVICE        │           │
│ KETO_WRITE_SERVICE       │           │
│ REDIS_HOST               │           │
│ REDIS_PORT               │           │
│ REDIS_PASSWORD           │           │
│ CORS_ALLOW_ORIGINS       │ *         │
│ CORS_ALLOW_METHODS       │           │
│ CORS_ALLOW_HEADERS       │           │
│ CORS_MAX_AGE             │ 0         │
│ CORS_ALLOW_CREDENTIALS   │ false     │
│ CORS_EXPOSE_HEADERS      │           │
│ GZIP_LEVEL               │ 5         │
╰──────────────────────────┴───────────╯

This will display all available environment variables and their current values. The default configuration is suitable for our phonebook project, but you can customize it by:

1. Creating a .env file in the project root
2. Adding your custom values following the format: KEY=VALUE
3. Reading more about environment configuration in the Env documentation

Testing your setup

Let's verify everything is working correctly:

1. First, build the service:

go build -o ./bin/phonebook .

2. Start the service:

bin/phonebook start

You should see output similar to this:

file '.env' not found
attempting to read env vars ...
⇨ http server started on [::]:8080
⇨ http server started on [::]:8081
⇨ http server started on [::]:8079

3. Test the health endpoint:

curl -H "Accept: application/json" http://127.0.0.1:8081/health/alive

You should receive a response like:

{"code":"20001","message":"success","errors":[],"payload":{"message":"ok","version":"2.2.1-default"}}

Git setup

First, let's remove the existing git folder to make room for our new repo:

rm -rf .git

Next, we'll initialize a new git repository and add the initial commit:

git init
git add .
git commit -m "Initial commit"

Great! You've successfully initialized a new project using the Codoworks Go boilerplate. In the next section, we'll start building the phonebook service by creating our first model.