diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index da9d925..3d993bd 100755 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -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", diff --git a/.mise.toml b/.mise.toml index be97891..12e6912 100644 --- a/.mise.toml +++ b/.mise.toml @@ -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" diff --git a/README.md b/README.md index 81a92aa..ac67c25 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,46 @@ - + # Go Dev Container - - -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. + +- [Using the Go Dev Container](#using-the-go-dev-container) +- [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 Workstation Setup](#initial-workstation-setup) + - [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. +## Using the Go Dev Container + +The container is stored in the [Github Container Registry](https://github.com/sarg3nt/go-dev-container/pkgs/container/go-dev-container). + +You can use the container in your own dev container config or use the [included one](#included-devcontainer-config). -### Go Tooling +## Included Tools + +See the base `mise` config file at `home/vscode/.config/mise/config.toml` for all tools and versions. + +### Go - golang - golangci-lint - goreleaser @@ -34,30 +59,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@` 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. + 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 managing specific versions of tooling you need for your Go project. + - `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=-bashhistory` +- Change `source=go-dev-container-plugins` to `source=-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` -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. +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. -## Initial Worksation Setup +- 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. + +Reopen in Container + +> **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. -Instructions to set up your worksation. +## 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 Workstation Setup](#initial-workstation-setup) for instructions on downloading and installing the fonts. + +## Initial Workstation Setup + +Instructions to set up your workstation. 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. @@ -82,45 +156,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 diff --git a/dev.sh b/dev.sh index b03bccb..a642766 100755 --- a/dev.sh +++ b/dev.sh @@ -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" diff --git a/images/reopen-in-container.png b/images/reopen-in-container.png new file mode 100644 index 0000000..231b27e Binary files /dev/null and b/images/reopen-in-container.png differ diff --git a/images/starship-prompt.png b/images/starship-prompt.png new file mode 100644 index 0000000..4e8878a Binary files /dev/null and b/images/starship-prompt.png differ diff --git a/install.sh b/install.sh new file mode 100755 index 0000000..e1ebf14 --- /dev/null +++ b/install.sh @@ -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 " + 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