craft

README

craft

• How to use ?
  • Easy install
  • Specific install
• Commands
• Craft file
• Plugins
  • Generic plugin
  • Golang plugin
    • With API layout
    • With Docker layout
  • Helm plugin
  • License plugin
• Examples

How to use ?

Easy install

go install gitlab.com/gotools-land/craft/cmd/craft@latest

Specific install

You can either download a specific release asset at https://gitlab.com/gotools-land/craft/-/releases or run the below shell commands to directly download an asset (just change the BINARY value).

BINARY="craft_linux_amd64"
DEST="craft"
DOWNLOAD_URL="$(curl -fsSL https://gitlab.com/api/v4/projects/47848839/releases/permalink/latest | jq -r ".assets.links[] | select(.name == \"$BINARY\") | .direct_asset_url")"
curl -fsSL "$DOWNLOAD_URL" -o "$DEST"
chmod +x "$DEST"

Commands

CLI commands:

• init: initializes a new craft projects. A few questions will be asked in the terminal to tune the generated layout:
  • project's description
  • project's main maintainer (can be anything, a group name, a person's name, alias, etc.)
  • will the project expose an api layer (golang based)
  • which openapi version the api layer will be (only asked if api layer is true)
  • will the project have a helm chart
• generate: generates the craft layout. Only works if the project was initialized (it has a .craft file at project's root). Available options are:
  • --force: forces the generation of a list of already generated files (.gitlab-ci.yml, sonar.properties, etc.)
  • --force-all: forces the generation of all generated files even if they exist (you may stage or stash your changes before running craft generate with this option).

Craft file

Craft project generation is based on root's .craft file, it can contain the following configurations:

• description: the project description.
• docker_registry: a specific docker registry URL that will be used for gitlab cicd docker build job and for helm docker pull registry.
• license: one of agpl-3.0, apache-2.0, bsd-2-clause, bsd-3-clause, bsl-1.0, cc0-1.0, epl-2.0, gpl-2.0, gpl-3.0, lgpl-2.1, mit, mpl-2.0, unlicense. When given, the according LICENSE file will be generated.
• maintainers: the list of project's maintainers. Each maintainer must at least have a name, they can also have an email and url.
• no_api: when provided, no API layer will be generated.
  • based on go-swagger when openapi_version is neither given or with v2 value
• no_chart: when provided, no helm chart in chart folder will be generated.
• no_ci: when provided, no GitLab CI/CD file will be generated. Otherwise, continuous integration is based on kilianpaquier/cicd integration templates.
• no_dockerfile: when provided, no Dockerfile will be generated.
• no_goreleaser: when provided, no .goreleaser.yml file will be generated (in any case, if the project isn't golang based, no file will be generated).
• no_makefile: when provided, no Makefile will be generated.
• no_sonar: when provided, no sonar.properties will be generated. As such, no sonar analysis job will be executed if no_ci is either not provided or false.
• openapi_version: one of v2, v3. When provided and no_api is either not provided or false, then it will generate the appropriate API layer.
  • Note that v3 is not implemented.
• port: exposed port in docker images (injected as environment variable BINARY_PORT in helm values).

Plugins

Craft generation is based on plugins. Each plugin detects from .craft configuration and project's files if it needs to generate its part (or not).

Overall, the following plugins are implemented:

• generic
• golang
• helm
• license
• openapi_v2

Generic plugin

Craft project generation for anything but golang (because it's the only coding language implemented for now) will be generated with the generic plugin.

The following layout will be created:

├── .craft (craft configuration file)
├── .gitlab-ci.yml (GitLab CI/CD file)
├── Makefile
└── README.md

It's a very simple generation with little features.

Golang plugin

Craft project generation for golang is following the present layout: https://github.com/golang-standards/project-layout.

├── cmd (executable binaries, prefix is useful for kubernetes identification)
│   ├── xyz (as many as desired CLIs)
│   │   ├── main.go
│   ├── cron-xyz (as many as desired cronjobs)
│   │   ├── main.go
│   ├── job-xyz (as many as desired jobs)
│   │   ├── main.go
│   ├── worker-xyz (as many as desired workers)
│   │   ├── main.go
├── internal (internal code)
├── pkg (public libraries)
├── testdata (tests files - expected generations, etc.)
├── .craft (craft configuration file)
├── .gitignore
├── .gitlab-ci.yml (GitLab CI/CD file)
├── .golangci.yml (golangci-lint configuration file)
├── go.mod
├── go.sum
├── Makefile
├── README.md
└── sonar.properties (sonar analysis properties)

With API layout

When the API option is present, then the following layout will be generated.

├── cmd
│   ├── <project_name>-api
│   │   ├── main.go (main associated to API layer)
├── internal
│   ├── api
│   │   ├── manual implementation with business layer for API layer
├── models
│   ├── generated models files by go-swagger for the API layer
├── pkg
│   ├── api
│   │   ├── generated client files by go-swagger for the API layer (consumers)
├── restapi
│   ├── generated server files by go-swagger for the API layer

With Docker layout

When the docker option is present and there's at least one executable, then the following files: Dockerfile, .dockerignore and launcher.sh will be generated.

├── cmd (executable binaries, prefix is useful for kubernetes identification)
│   ├── xyz (as many as desired CLIs)
│   │   ├── main.go
│   ├── cron-xyz (as many as desired cronjobs)
│   │   ├── main.go
│   ├── job-xyz (as many as desired jobs)
│   │   ├── main.go
│   ├── worker-xyz (as many as desired workers)
│   │   ├── main.go
├── .dockerignore
├── Dockerfile
└── launcher.sh (only when there's at least one main.go in cmd folder, parses the BINARY_NAME environment variable to run the right executable)

Helm plugin

The helm plugin is in charge of generating the helm chart for the project. Depending on implemented coding languages, values.yaml file will contain values for cronjobs, jobs or workers.

For instance, associated with golang plugin, kubernetes executables will be parsed from cmd folder.

The following layout will be created:

├── chart (folder with helm chart templates and values)
│   ├── .craft (override values for helm chart)
└── .craft (craft configuration file)

License plugin

The license plugin is only in charge of retrieving the appropriate LICENSE file according to .craft > license value.

Examples

You may consult the examples for more information and details on generated files.