Skip to content

Latest commit

 

History

History
110 lines (75 loc) · 3.71 KB

DEVELOPMENT.md

File metadata and controls

110 lines (75 loc) · 3.71 KB

Development

Within containers

If you are using GitHub Codespaces or Visual Studio Code and you have Docker installed, just open this repository in VS code. We've preconfigured everything for you, so that you can start code quite easily. :3

Local development

In order to work on Mahlzeit, several tools are required:

  • Go 1.20 compiler or newer (since the application is written in Go)
  • npm for the web development.
  • just for making use of our Justfile, which handles the more complex stuff.

Optional, but recommended:

  • docker compose for quickly spinning up development databases
  • direnv

Once you've installed the tools, run just prepare to setup your development environment. Some helper tools are going to be downloaded as well.

Working on templates

In order to work with the templates and their styling, we need npm set up. We aim to remove it at a later stage, but for now, it's easier to work with it and the Vite ecosystem.

In order to start Vite and enabling on-the-fly compilation for CSS/JS assets, open a terminal and run:

$ just dev

This starts the "asset server" on port 5173, which is then injected into the templates with the manifest.partial.tmpl.

Building the application

Building the application is as simple as:

$ just build

This outputs a binary called mahlzeit. Because the compiled assets are not embedded into the binary at this moment, they need to be copied along with the binary. We've provided a simple command for you that generates an archive with all necessary files.

$ just package

The files in the repository are prepared for the development with docker compose. In order to start the application, we need to create the database and after that we're ready to go!

$ docker compose up -d  # creating the database container
$ dbmate --wait up      # applying the migrations
$ go run ./cmd/mahlzeit # starting the application

Now Mahlzeit is starting and reachable on localhost:4000!

Hot code reload

We use air to automatically restart mahlzeit when code changes.

To start the server with air, just run just dev in the project root directory.

Working with the database

Creating the test database

Once dbmate is installed, you can spin up an empty database with dbmate up. As of today, there's no seed data available, but we aim to provide it in the future.

Adding a new migration

dbmate is also used for creating new migrations. Assuming we want to create a migration for adding a new table, e.g. for recipe utensils, we might do it the following way:

  1. Create a new migration with a descriptive name. dbmate new add-utensils-table

  2. Open the new migration file: editor db/migrations/*-add-utensils-table.sql

  3. Fill the file with the following content:

    -- migrate:up
create table utensils
(
    id   bigint primary key generated by default as identity,
    name text not null
);

-- migrate:down
drop table utensils;

  4. Apply the new migration by running dbmate up. The schema.sql should be updated automatically afterwards.

  5. Done!

Recommendations for new migrations

  1. Use bigint for the identifier. Although we might never reach the limit of 4-byte length integers, it's better to be prepared.
  2. Use not null where possible. Working with nullables or nil in Go can be a pain, so try to avoid nullable values. It's recommended to set it to not null with a default value.
  3. Use lowercase SQL. It's just a preference, but it's consistent with the rest of the project.