|
1 | | -# Go Project Template |
| 1 | +# Distillery |
2 | 2 |
|
3 | | -This is an opinionated go project template to use as a starting point for new projects. |
| 3 | +**Status: alpha** -- things are not fully implemented, things are likely broken. Things are likely to change. Name |
| 4 | +might change, but I like `dist` for the binary name. |
4 | 5 |
|
5 | | -## Features |
| 6 | +## Overview |
6 | 7 |
|
7 | | -- Builds with [GoReleaser](https://goreleaser.com) |
8 | | - - Automated with GitHub Actions |
9 | | - - Signed with Cosign (providing you generate a private key) |
10 | | -- Linting with [golangci-lint](https://golangci-lint.run/) |
11 | | - - Automated with GitHub Actions |
12 | | -- Builds with Docker |
13 | | - - While designed to use goreleaser, you can still just run `docker build` |
14 | | -- Apple Notary Signing Support |
15 | | -- Opinionated Layout |
16 | | - - Never use `internal/` folder |
17 | | - - Everything is under `pkg/` folder |
18 | | -- Commits must meet [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) |
19 | | - - Automated with GitHub Actions ([commit-lint](https://github.com/conventional-changelog/commitlint/#what-is-commitlint)) |
20 | | -- Automatic Dependency Management with [Renovate](https://github.com/renovatebot/renovate) |
21 | | -- Automatic [Semantic Releases](https://semantic-release.gitbook.io/) |
22 | | -- Documentation with Material for MkDocs |
23 | | -- API Server Example |
24 | | - - Uses Gorilla Mux (yes it's been archived, still the best option) |
25 | | -- Stubbed out Go Tests (**note:** they are not comprehensive) |
| 8 | +Without a doubt, [homebrew](https://brew.sh) has had a major impact on the macOS ecosystem. It has made it easy to |
| 9 | +install software and keep it up to date. It has been around for 15 years and while it has evolved over time, its core |
| 10 | +technology hasn't changed, and 15 year is an eternity in the tech world. I love homebrew, but I think there's room for |
| 11 | +another tool. |
26 | 12 |
|
27 | | -### Opinionated Decisions |
| 13 | +The goal of this project is to leverage the collective power of all the developers out there that are using tools like |
| 14 | +[goreleaser](https://goreleaser.com/) and [cargo-dist](https://github.com/axodotdev/cargo-dist) and many others to |
| 15 | +pre-compile their software and put their binaries up on GitHub or GitLab and install the binaries. |
28 | 16 |
|
29 | | -- Uses `init` functions for registering commands globally. |
30 | | - - This allows for multiple `main` package files to be written and include different commands. |
31 | | - - Allows the command code to remain isolated from each other and a simple import to include the command. |
| 17 | +## Goals |
32 | 18 |
|
33 | | -### Multi-Platform Builds |
| 19 | +- Make it simple to install binaries on your system from multiple sources |
| 20 | +- Do not rely on a centralized repository of package managers |
| 21 | +- Support binary verifications and signatures if exist, prompt the user if they don't |
| 22 | +- Support multiple platforms and architectures |
34 | 23 |
|
35 | | -This project is designed to build for multiple platforms, including macOS, Linux, and Windows. It also supports |
36 | | -multiple architectures including amd64 and arm64. |
| 24 | +## TODO |
37 | 25 |
|
38 | | -The goreleaser configuration is set up to build for all platforms and architectures by default. It even supports pushing |
39 | | -multi-architecture docker manifests by default. Some knowledge about GoReleaser's configuration is required should you |
40 | | -want to remove these capabilities. |
| 26 | +- [ ] implement signature verification |
| 27 | +- [ ] implement multiple additional sources |
41 | 28 |
|
42 | | -### Apple Notary Signing |
| 29 | +## Usage |
43 | 30 |
|
44 | | -This makes use of a tool called [quill](https://github.com/anchore/quill). To make use of this feature you will need |
45 | | -to have an Apple Developer account and be able to create an Developer ID certificate. |
46 | | - |
47 | | -The workflow is designed to pull the necessary secrets from 1Password. This is done to keep the secrets out of the |
48 | | -GitHub Actions logs. The secrets are pulled from 1Password if the event triggering the workflow is a tag **AND** the |
49 | | -actor is the owner of the repository. This is to prevent forks from being able to pull the secrets and is an extra |
50 | | -guard to help prevent theft. |
51 | | - |
52 | | -GoReleaser is configured to always sign and notarize for macOS. However, it will not notarize if the build is a snapshot. |
53 | | - |
54 | | -If configured properly, the binaries located within the archives produced by GoReleaser will be signed and notarized |
55 | | -by the Apple Notary Service and will automatically run on any macOS system without having to approve it under System |
56 | | -Preferences. |
57 | | - |
58 | | -If you do not wish to use 1Password simply export the same environment variables using secrets to populate them. The |
59 | | -`QUILL_SIGN_P12` and `QUILL_NOTARY_KEY` need to be base64 encoded or paths to the actual files. |
60 | | - |
61 | | -## Building |
62 | | - |
63 | | -The following will build binaries in snapshot order. |
64 | | - |
65 | | -```console |
66 | | -goreleaser --clean --snapshot --skip sign |
67 | | -``` |
68 | | - |
69 | | -**Note:** we are skipping signing because this project uses cosign's keyless signing with GitHub Actions OIDC provider. |
70 | | - |
71 | | -You can opt to generate a cosign keypair locally and set the following environment variables, and then you can run |
72 | | -`goreleaser --clean --snapshot` without the `--skip sign` flag to get signed artifacts. |
73 | | - |
74 | | -Environment Variables: |
75 | | -- |
76 | | -- COSIGN_PASSWORD |
77 | | -- COSIGN_KEY (path to the key file) (recommend cosign.key, it is git ignored already) |
78 | | - |
79 | | -```console |
80 | | -cosign generate-key-pair |
81 | | -``` |
82 | | - |
83 | | -## Configure |
84 | | - |
85 | | -1. Rename Repository |
86 | | -2. Generate Cosign Keys (optional if you want to run with signing locally, see above) |
87 | | -3. Update `.goreleaser.yml`, search/replace go-project-template with new project name, adjust GitHub owner |
88 | | -4. Update `main.go`, |
89 | | -5. Update `go.mod`, rename go project (using IDE is best so renames happen across all files) |
90 | | - |
91 | | -### Docker |
92 | | - |
93 | | -The Dockerfile is set up to build the project and then copy the artifacts from the build into the final image. It is |
94 | | -also configured to allow you to just run `docker build` directly if you do not want to use GoReleaser. |
95 | | - |
96 | | -To make things easier and faster, the Dockerfile has a default build argument set to `go-project-template`. GoReleaser |
97 | | -will pass the new project name down (if you update the `.goreleaser.yml` file) and the Dockerfile will use that instead. |
98 | | - |
99 | | -However, it would be better longer term to update this argument in the file or remove it all together. |
100 | | - |
101 | | -### Signing |
102 | | - |
103 | | -Signing happens via cosign's keyless features using the GitHub Actions OIDC provider. |
104 | | - |
105 | | -### Releases |
106 | | - |
107 | | -In order for Semantic Releases and GoReleaser to work properly you have to create a PAT to run Semantic Release |
108 | | -so it's actions against the repository can trigger other workflows. Unfortunately there is no way to trigger |
109 | | -a workflow from a workflow if both are run by the automatically generated GitHub Actions secret. |
110 | | - |
111 | | -1. Create PAT that has content `write` permissions to the repository |
112 | | -2. Create GitHub Action Secret |
113 | | - - `SEMANTIC_GITHUB_TOKEN` -> populated with PAT from step 1 |
114 | | -3. Done |
115 | | - |
116 | | -## Documentation |
117 | | - |
118 | | -The project is built to have the documentation right alongside the code in the `docs/` directory leveraging Mkdocs Material. |
119 | | - |
120 | | -In the root of the project exists mkdocs.yml which drives the configuration for the documentation. |
121 | | - |
122 | | -This README.md is currently copied to `docs/index.md` and the documentation is automatically published to the GitHub |
123 | | -pages location for this repository using a GitHub Action workflow. It does not use the `gh-pages` branch. |
124 | | - |
125 | | -### Running Locally |
126 | | - |
127 | | -```console |
128 | | -make docs-serve |
129 | | -``` |
130 | | - |
131 | | -OR (if you have docker) |
132 | | - |
133 | | -```console |
134 | | -docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material |
135 | | -``` |
| 31 | +1. Download `dist` place it in your path |
| 32 | +2. Add `$HOME/.distillery/bin` to your path |
| 33 | +3. Run `dist install owner/repo` to install a binary from GitHub Repository |
| 34 | +4. Enjoy |
0 commit comments