nicolab / goflow

A base workflow for Golang projects: Docker + Golang + inspiration from standards.

Go Flow

A base workflow for Golang projects, layout inspired by the Golang standards.

Docker + Golang + inspiration from standards.

• Examples: Minimal Go Flow Project Layout
• Proposals
• Proposals: Basic project layout

Quick Start

Goflow must be installed from a clean repository (existing and nothing to validate).

Create a new one if needed:

git init
echo 'TODO' > ./README.md
git add .
git commit -m "Initial commit"

Get goflow directory:

• You can get it with git clone [email protected]:Nicolab/goflow.git.
• You can use git submodule.
• Simply copy / paste...
• Personally I use git subrepo.

Example with git subrepo in an existing Git repository:

# get the goflow subrepo
git subrepo clone https://github.com/Nicolab/goflow.git

After downloading the goflow directory, edit the config file: ./goflow/conf/dev/docker.sh (mainly: dev_container_name).

From now on you need the files of your project (go.mod, main.go). If your project directory is empty, you can use the minimal Go Flow Project Layout as inspiration (or starter kit).

Then, always from your project directory:

./goflow/build/dev/build-image # create goflow-dev image
./goflow/scripts/dev/console # run the container and get a shell inside

Now, from the container:

cd /home
# install dev tools globally in the container
./go/goflow/scripts/dev/install-container-stack
cd /home/go
# the app uses Go mod
./goflow/scripts/dev/watch # or ./goflow/scripts/dev/watch-debug

It's installed! Happy Coding in the Go flow ;)

NOTE: Some scripts located in ./goflow/scripts/dev/ directory, are in the ./bin/ directory of the Minimal Go Flow Project Layout. With these shortcuts you can run for example: ./bin/dev/console from the host and ./bin/dev/watch from the container.

Usage

Config

See the config files.

Host

Run/exec the goflow-dev container:

./goflow/scripts/dev/console

Stop and remove goflow-dev container:

./goflow/scripts/dev/rm-container

Container

Execute the Go program (go run by default):

./goflow/scripts/dev/exec

Run the Go program and watch the code change (for reloading):

./goflow/scripts/dev/watch

Same with Delve:

./goflow/scripts/dev/watch-debug

Now, you can connect your favorite code editor to the Delve server.

From the host you can also exec: dlv connect localhost:2345 or in one: dlv connect localhost:2345 & ./goflow/scripts/dev/console

Docker compose

goflow can be used with docker-compose.

You can see the sample file: ./goflow/build/dev/docker-compose.yml and copy / paste in your docker-compose.yml file. Also you can use it directly, with docker-compose -f ./goflow/build/dev/docker-compose.yml command or the shortcuts:

• ./goflow/scripts/dev/dc (docker-compose shortcut).
  • Example: ./goflow/scripts/dev/dc up
• and ./goflow/scripts/dev/dce (docker-compose exec shortcut).
  • Example: ./goflow/scripts/dev/dce app bash (enter to the container app).

How to Update

If you need to keep your Go Flow up to date with the recent changes made to Go Flow project, you can always fetch and merge them from this repo back into your own project:

git subrepo pull goflow

You can show the clean main history: git log --oneline --graph 👍

If you don't use git subrepo and you encounter an unrelated history error, add the flag: --allow-unrelated-histories to prevent that Git refusing to merge unrelated histories.

Update the remote tracking

If you want to add or to update a remote branch to track:

git remote add -t master goflow git@github:Nicolab/goflow.git

git remote add -t remote-branch remote-name remote-url You can use multiple "-t branch" options to grab multiple branches.

How to uninstall

Remove the goflow directory:

rm -rf goflow

Remove the remote URL (if you added it):

git remote rm goflow

Verify it's gone: git remote -v Note: git remote rm does not delete the remote repository from the server. It simply removes the remote and its references from your local repository.

Tips

Layout

To start quickly, copy / paste the Minimal Go Flow Project Layout. It will give you shortcuts, configurations and a basic structure eavely used in dev and prod by many Go projects.

Docker volumes

You can mount as many files and folders as you want. It's a simple Docker command that you can customize at will!

.bashrc:

To customize the .bashrc file, you can mount the .bashrc file in volume via ./goflow/conf/dev/docker.sh file.

Example:

-v "${PWD}"/goflow/build/dev/files/.bashrc:/home/gopher/.bashrc \

.ssh:

Useful to add ssh key or ssh config.

Example:

-v "${PWD}"/goflow/build/dev/files/.ssh/config:/home/gopher/.ssh/config \

.gitconfig:

Custom GIT config.

Example:

-v "${PWD}"/goflow/build/dev/files/.gitconfig:/home/gopher/.gitconfig \

Troubleshooting

Max user files watches

If you reach the default limit of your OS, you should increase the amount of inotify watchers.

If you are running Debian, RedHat, or another similar Linux distribution, run the following in a terminal that set a new limit temporary:

sudo sysctl fs.inotify.max_user_watches=524288 \
&& sudo sysctl -p \
&& cat /proc/sys/fs/inotify/max_user_watches

TODO

• Handle locales in build/dev/Dockerfile.
• Improve the concept (symplify the install, usage and add more docs).

LICENSE

MIT (c) 2018, Nicolas Tallefourtane.

Author

Nicolas Talle