Skip to content

Latest commit

 

History

History
212 lines (147 loc) · 5.43 KB

CONTRIBUTING.md

File metadata and controls

212 lines (147 loc) · 5.43 KB
Raw

Contributor Guide

Welcome to Smee! We are really excited to have you. Please use the following guide on your contributing journey. Thanks for contributing!

Table of Contents

Context

Smee is a DHCP and PXE (TFTP & HTTP) service. It is part of the Tinkerbell stack and provides the first interaction for any machines being provisioned through Tinkerbell.

Architecture

Design Docs

Details and diagrams for Smee are found here.

Code Structure

Details on Smee's code structure is found here (WIP)

Prerequisites

DCO Sign Off

Please read and understand the DCO found here.

Code of Conduct

Please read and understand the code of conduct found here.

Setting up your development environment

Dependencies

Build time dependencies

Runtime dependencies

At runtime Smee needs to communicate with a Tink server. Follow this guide for running Tink server.

Development

Building

At the moment, these instructions are only stable on Linux environments

To build Smee, run:

# build all ipxe files, embed them, and build the Go binary
# Built binary can be found in the top level directory.
make build

To build the amd64 Smee container image, run:

# make the amd64 container image
# Built image will be named smee:latest
make image

To build the IPXE binaries and embed them into Go, run:

# Note, this will not build the Smee binary
make bindata

To build Smee binaries for all distro

Unit testing

To execute the unit tests, run:

make test

# to get code coverage numbers, run:
make coverage

Linting

To execute linting, run:

# runs golangci-lint
make lint

# runs goimports
make goimports

# runs go vet
make vet

Linting of Non Go files

# lints non Go files like shell scripts, markdown files, etc
# this script is used in CI run, so be sure it passes before submitting a PR
./.github/workflows/ci-non-go.sh

Functional testing

  1. Create a hardware record in Tink server - follow the guide here
  2. boot the machine

Running Smee

  1. Be sure all documented runtime dependencies are satisfied.

  2. Define all environment variables.

    # MIRROR_HOST is for downloading kernel, initrd
export MIRROR_HOST=192.168.2.3
# PUBLIC_FQDN is for phone home endpoint
export PUBLIC_FQDN=192.168.2.4
# DOCKER_REGISTRY, REGISTRY_USERNAME, REGISTRY_PASSWORD, TINKERBELL_GRPC_AUTHORITY, TINKERBELL_CERT_URL are needed for auto.ipxe file generation
# TINKERBELL_GRPC_AUTHORITY, TINKERBELL_CERT_URL are needed for getting hardware data
export DOCKER_REGISTRY=192.168.2.1:5000
export REGISTRY_USERNAME=admin
export REGISTRY_PASSWORD=secret
export TINKERBELL_GRPC_AUTHORITY=tinkerbell.tinkerbell:42113
export TINKERBELL_CERT_URL=http://tinkerbell.tinkerbell:42114/cert
# FACILITY_CODE is needed for ?
export FACILITY_CODE=onprem
export DATA_MODEL_VERSION=1
# API_AUTH_TOKEN, API_CONSUMER_TOKEN are needed to by pass panicking in main.go main func
export API_AUTH_TOKEN=none
export API_CONSUMER_TOKEN=none

  3. Run Smee

    # Run the compiled smee
sudo ./smee -http-addr 192.168.2.225:80 -tftp-addr 192.168.2.225:69 -dhcp-addr 192.168.2.225:67

  4. Faster iterating via go run

    # after the ipxe binaries have been compiled you can use `go run` to iterate a little more quickly than building the binary every time
sudo go run ./smee -http-addr 192.168.2.225:80 -tftp-addr 192.168.2.225:69 -dhcp-addr 192.168.2.225:67

Pull Requests

Branching strategy

Smee uses a fork and pull request model. See this doc for more details.

Quality

CI

Smee uses GitHub Actions for CI. The workflow is found in .github/workflows/ci.yaml. It is run for each commit and PR.

Code coverage

Smee does run code coverage with each PR. Coverage thresholds are not currently enforced. It is always nice and very welcomed to add tests and keep or increase the code coverage percentage.

Pre PR Checklist

This checklist is a helper to make sure there's no gotchas that come up when you submit a PR.