Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add-badges-to-README.md #8

Merged
merged 11 commits into from
Oct 29, 2024
6 changes: 3 additions & 3 deletions .devcontainer/devcontainer.json
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
// cSpell:ignore FUMPT ciiqr darkriszty euskadi Gruntfuggly huizhou githd kato mhutchie tamasfe koehler yzhang gopls gofumpt docomment
{
"name": "go-dev-container",
// "runArgs": [
// "--name=go-dev-container-dev"
// ],
"runArgs": [
"--name=go-dev-container"
],
"mounts": [
"source=go-dev-container-bashhistory,target=/commandhistory,type=volume",
"source=go-dev-container-plugins,target=/home/vscode/.vscode-server/extensions,type=volume",
Expand Down
10 changes: 5 additions & 5 deletions .mise.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@
# supports arbitrary env vars so mise can be used like direnv/dotenv
#EXAMPLE = 'bar'

[tools]
# specify single or multiple versions of specific tools you want installed for this project.
golang = '1.23.2'
golangci-lint = '1.61.0'
goreleaser = "2.3.2"
kubectl = "1.30"
# Below are examples.
# [tools]
# golang = '1.23.1'
# golangci-lint = '1.61.0'
# goreleaser = "2.3.2"
151 changes: 100 additions & 51 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,39 @@
<!--cspell:ignore sarg -->
<!--cspell:ignore sarg trivy gitui kubectx Fira Firacode Caskaydia Consolas -->
# Go Dev Container

<!-- [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/sarg3nt/cert-manager-webhook-infoblox-wapi/badge)](https://scorecard.dev/viewer/?uri=github.com/sarg3nt/cert-manager-webhook-infoblox-wapi)
[![CodeQL](https://github.com/sarg3nt/cert-manager-webhook-infoblox-wapi/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/sarg3nt/cert-manager-webhook-infoblox-wapi/actions/workflows/github-code-scanning/codeql)
[![Release](https://github.com/sarg3nt/cert-manager-webhook-infoblox-wapi/actions/workflows/release.yml/badge.svg)](https://github.com/sarg3nt/cert-manager-webhook-infoblox-wapi/actions/workflows/release.yml) -->

A Go Dev Container using `mise` to install Go and other conventinet tools. `mise` can then be used to install various other go versions as needed.

[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/sarg3nt/go-dev-container/badge)](https://scorecard.dev/viewer/?uri=github.com/sarg3nt/go-dev-container)
[![Scorecard supply-chain security](https://github.com/sarg3nt/go-dev-container/actions/workflows/scorecard.yml/badge.svg)](https://github.com/sarg3nt/go-dev-container/actions/workflows/scorecard.yml)
[![trivy](https://github.com/sarg3nt/go-dev-container/actions/workflows/trivy.yml/badge.svg)](https://github.com/sarg3nt/go-dev-container/actions/workflows/trivy.yml)
[![Dependabot Updates](https://github.com/sarg3nt/go-dev-container/actions/workflows/dependabot/dependabot-updates/badge.svg)](https://github.com/sarg3nt/go-dev-container/actions/workflows/dependabot/dependabot-updates)
[![Dependency Review](https://github.com/sarg3nt/go-dev-container/actions/workflows/dependency-review.yml/badge.svg)](https://github.com/sarg3nt/go-dev-container/actions/workflows/dependency-review.yml)
[![Release](https://github.com/sarg3nt/go-dev-container/actions/workflows/release.yml/badge.svg)](https://github.com/sarg3nt/go-dev-container/actions/workflows/release.yml)

A Go Dev Container using `mise` to install Go and other convenient tools.
`mise` can then be used to install various other Go versions as needed.

- [Included Tools](#included-tools)
- [Go](#go)
- [Utilities](#utilities)
- [Using `mise` to Manage Go Versions](#using-mise-to-manage-go-versions)
- [Included `.devcontainer` Config](#included-devcontainer-config)
- [Dev Container Setup](#dev-container-setup)
- [`dev.sh`](#devsh)
- [Starship](#starship)
- [Initial Worksation Setup](#initial-worksation-setup)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Typo for 'workstation'? There seems to be 8 instances in total in this file.

Copy link
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed all

- [WSL on Windows](#wsl-on-windows)
- [Windows Font Install](#windows-font-install)
- [Windows Terminal Font Setup](#windows-terminal-font-setup)
- [Linux Font Install](#linux-font-install)
- [Visual Studio Code Font Setup](#visual-studio-code-font-setup)
- [Contributions](#contributions)
- [License](#license)
- [Author](#author)

## Tools Included

See the root `mise` config file at `home/vscode/.config/mise/config.toml` for all tools and versions.
## Included Tools

See the base `mise` config file at `home/vscode/.config/mise/config.toml` for all tools and versions.

### Go Tooling
### Go
- golang
- golangci-lint
- goreleaser
Expand All @@ -34,30 +52,79 @@ See the root `mise` config file at `home/vscode/.config/mise/config.toml` for al

## Using `mise` to Manage Go Versions

1. Copy the `.mise.toml` file from the root of this repo to your projects repo root and modify it as needed.
1. The provided `.devcontainer` will automatclly call `mise install` to install the custom versions of the applications.
1. After the container is started and you shell into it you may need to call `mise use golang@<version>` to switch to the new version. The included `help` explains how to do this in more detail and other `mise` commands you can use.
1. Copy the `.mise.toml` file from the root of this repo to your project's root and modify it as needed.
1. The provided `.devcontainer` will automatically call `mise install` to install the custom versions of the applications.
1. After the container is started and you exec into it, `mise` will automatically install the app versions listed in the `.mise.toml` file.
1. Other applications can also be installed by editing the `.mise.toml` file.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Numbered steps were not incremented here.

Copy link
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They are not supposed to be. This is Markdown best practice. The downstrem instance automatically numbers them correctly. This makes adding new items in random places and moving items around the list easier.

Run `mise help` for examples.

## Included `.devcontainer` Config

This project not only builds the dev container into the provided Docker container it also includes an example implemantion in the `.devontainer` directory.
Do the following to use this implmention.
This repository also includes an example on how to use the built Go dev container.

Do the following to use this example.

1. Clone down the repository.
`git clone https://github.com/sarg3nt/go-dev-container.git`
2. Ensure your target project does not already have a `.devcontainer` directory. If it does, you will either need to rename it for testing or delete it.
3. Copy the `.devcontainer` directory to your project.
4. Copy the following files to the root of your project.
These are optional but encouraged.
- `.mise.toml`: The config file for manageing specific versions of tooling you need for your Go project.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor type for 'managing'.

Copy link
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed

- `cspell.json`: The cspell config for spell checking in your project, edit to add any specific words that your project needs.
- `dev.sh`: Helps launch VSCode and exec into the dev container. This file needs some modification to use in your repository. See [dev.sh](#devsh) for instructions.

We've included an `install.sh` script to automate the process of copying the above files into your project directory.

The script must be ran from the root of the `go-dev-container` project.

**Example:** `./install.sh ~/src/my-go-project`

### Dev Container Setup

Once you've followed the above instructions to copy the needed files to your project, perform the following to configure them.

Edit the `devcontainer.json` file to make the following changes.

- Change `name` from `go-dev-container` to the name of your project.
- Change `--name` in `runargs` from `go-dev-container` to the name of your project.
- Change `source=go-dev-container-bashhistory` to `source=<YOUR-PROJECT>-bashhistory`
- Change `source=go-dev-container-plugins` to `source=<YOUR-PROJECT>-plugins`

> **NOTE:** You may be tempted to find and replace `go-dev-container` with the name of your project, however the `image` for the container is called `go-dev-container` so that would break things. If you want to do a controlled replacement you can, just be careful not to replace that one line.

### `dev.sh`

This script is used to easily start VSCode and exec into the Dev Container from the terminal that it is ran from. This frees the developer from having to use the VSCode integrated terminal.

You can run `dev.sh` in multiple terminals once VSCode is running and the container has started to easily exec into it.

- Open the `dev.sh` file and set a `docker_exec_command` if desired, this is optional but if this repo is used a lot, it is a nice to have. This will create a command in the users `.bashrc` and `.zshrc` to quickly exec into this running dev container.
- Change `project_name` to match the name of the repository.
**Example:** If your root project repository is called `my-go-project` then set `project_name` to `my-go-project`

To use the `./dev.sh` script, simply run it, then when VS Code opens, there should be a prompt at the bottom right of the editor saying "Folder contains a Dev Container . . .". Click the "Reopen in Container" button and VS Code will open the dev container and attach to it.

<img src="images/reopen-in-container.png" alt="Reopen in Container" width="400"/>

1. Cone down the rpository.
1. Copy the `.devcontainer` directory to your project. Note: you should not already have a `.devctonaer` directory or things could get weird.
1. Copy the following files to the root of your projects. All of these are optional but encouraged.
- `.mise.toml`
- `cspell.json` Edit this with your specific words that you need to `cspell` to ignroe globally.
- `dev.sh` This file helps launch and exec into the dev container.
1. Starship has a custom Power Line command prompt we include, for it to function properly you need one of the Nerd Fonts installed. See the [Initial Worksation Setup](#initial-worksation-setup) documentiaon for instrucitons on downloading and installing the fonts.
> **NOTE:** If you have not opened the dev container before or if it has been updated it will download the container from Github, which can take a while.

## Starship

Starship is a custom Power Line command prompt we include.

![Starship Prompt](images/starship-prompt.png)

For Starship to function properly you need a [Nerd Font](https://www.nerdfonts.com/) installed from [Nerd Fonts Downloads](https://www.nerdfonts.com/font-downloads).

See [Initial Worksation Setup](#initial-worksation-setup) for instructions on downloading and installing the fonts.

## Initial Worksation Setup

Instructions to set up your worksation.
For more information on Dev Containers check out the [official docs](https://code.visualstudio.com/docs/devcontainers/containers).

### WSL
### WSL on Windows

1. If you will be building Docker containers in Windows, then install Docker Desktop for Windows following [Docker's instructions](https://docs.docker.com/desktop/install/windows-install/). If you do not need Docker for Windows support then you can [directly install Docker inside of Ubuntu](https://docs.docker.com/engine/install/ubuntu/) **AFTER** you install WSL and Ubuntu in the following steps.
1. Install VS Code from the [Visual Studio Code website](https://code.visualstudio.com/download) or from the Microsoft Store.
Expand All @@ -82,45 +149,27 @@ Download your chosen font and [install it in Windows](https://support.microsoft.
1. Under `Additional Settings` select `Appearance`
1. Under `Font Face` select the name of the font you downloaded, for example if you chose the "Firacode Nerd Font" then you'd choose `Firacode NF` You may need to check `Show all items` or restart Windows Terminal to see the new fonts.

#### Visual Studio Code Font Setup
### Linux Font Install

See [How to Install New (or Nerd) Fonts on Linux (Ultimate Guide)](https://linuxtldr.com/install-fonts-on-linux/) for instructions.

### Visual Studio Code Font Setup

The fonts must be installed in your operating system to be used in VSCode. If you are running VSCode on Windows and using it in Linux inside of WSL you would still install the fonts in Windows.

1. Select `File` --> `Preferences` --> `Settings`
1. Expand `Text Editor` --> select `Font`
1. In the `Font Family` text box paste the following:

> **NOTE:** This assumes you chose "FiraCode NF", if not, replace the first font name with the name of the font you installed in Windows.
> **NOTE:** This assumes you chose "FiraCode NF", if not, replace the first font name with the name of the font you installed in Windows.

```
'FiraCode NF', 'CaskaydiaCove NF', Consolas, 'Courier New', monospace
```

## Initial Dev Container and Project Setup

The following contains initial project setup.

### `dev.sh`

This script is used to more easily start Visual Studio code and hop into the Dev Container from the terminal that it is ran from.

- Open the `dev.sh` file and set a `docker_exec_command` if desired, this is optional but if this repo is used a lot, it is a nice to have. This will create a command in the users `.bashrc` and `.zshrc` to quickly exec into this running dev container.
- Change `project_name` to match the name of the repository. Exaple: If your root project repository is called `my-go-project` then set `project_name` to `my-go-project`

To use the `./dev.sh` script, simply run it, then when VS Code opens, there should be a prompt at the bottom right of the editor saying "Folder contains a Dev Container . . .". Click the "Reopen in Container" button and VS Code will open the dev container and attach to it.
![Reopen in Container](.devcontainer/reopen_in_container.png)
> **NOTE:** If you have not opened the dev container before or if it has been updated it will download the container from Github, which can take a while.

### Dev Container Setup

Edit the `devcontainer.json` file to make the following changes.

- Change the `name`, by replacing "Template" to the name of your project.
- Replace all instances of `template-` with your projects name and a dash. Example: `my-project-`

The rest of this doc is typically kept in all projects that use the dev container.

## Contributions

If you would like to contribute to this projects, please, open a PR via GitHub. Thanks.
Contributions are welcome via the standard Github Fork --> PR process.

## Author

Expand Down
4 changes: 2 additions & 2 deletions dev.sh
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,8 @@ main() {
local docker_exec_command="gdc"
# Name of the project folder
local project_name="go-dev-container"
# Name of the container
local container_name="go-dev-container"
# Name of the container. This assumes you are using the same name as the project folder in the devcontainer.json file 'runargs' section.
local container_name="${project_name}"
# User being created in the container
local container_user="vscode"

Expand Down
Binary file added images/reopen-in-container.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/starship-prompt.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
66 changes: 66 additions & 0 deletions install.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
#!/bin/bash
#
# This script will start the dev container and open an interactive prompt into it.
#

set -euo pipefail
IFS=$'\n\t'

# Check if user is using Docker Deskop for Windows or the native Docker Engine.
main() {
# shellcheck source=/dev/null
if [[ ! -f "usr/bin/lib/sh/colors.sh" ]]; then
echo "You do not appear to be in the go-dev-container project directory."
echo "This script must be ran from the root of the go-dev-container project directory."
exit 1
fi
source "usr/bin/lib/sh/colors.sh"

local project_path=""
project_path="${1-}"
if [[ -z "${project_path}" ]]; then
echo -e "${RED}The path to your project was not passed in and is required.${NC}"
echo -e "${CYAN}Usage:${NC} $0 <path-to-your-project>"
exit 1
fi

# Remove trailing slash from project_path if it exists
project_path="${project_path%/}"

if [[ ! -d "${project_path}" ]]; then
echo -e "${RED}The path to your project does not exist.${NC}"
exit 1
fi

echo -e "${BLUE}This script will copy the following directories and files into${NC} ${project_path}"
echo -e " .devcontainer"
echo -e " .mise.toml"
echo -e " cspell.json"
echo -e " dev.sh"
read -r -p "$(echo -e "${CYAN}Do you wish to continue? (y/n): ${NC}")" response
if [[ "$response" != "y" ]]; then
echo -e "${RED}Aborting.${NC}"
exit 1
fi
echo ""

echo -e "${BLUE}Copying files to ${project_path}${NC}"

echo -e " ${GREEN}Copying${NC} .devcontainer ${GREEN}directory${NC}"
cp -r ".devcontainer" "${project_path}/"
echo -e " ${GREEN}Copying${NC} .mise.toml"
cp ".mise.toml" "${project_path}/"
echo -e " ${GREEN}Copying${NC} cspell.json"
cp "cspell.json" "${project_path}/"
echo -e " ${GREEN}Copying${NC} dev.sh"
cp "dev.sh" "${project_path}/"

echo ""
echo -e "${CYAN}You must now update the values in the${NC} ${project_path}/.devcontainer/devcontainer.json ${CYAN}and${NC} ${project_path}/dev.sh ${CYAN}files.${NC}"
echo -e "${CYAN}See${NC} README.md ${CYAN}for instructions.${NC}"

}

if ! (return 0 2>/dev/null); then
(main "$@")
fi