Skip to content

Commit bbbd54a

Browse files
pdesjardins90pdesjardins90
committed
x(docs): update documentation
1 parent 2a981a3 commit bbbd54a

File tree

4 files changed

+70
-38
lines changed

4 files changed

+70
-38
lines changed

‎.github/workflows/cd.yaml‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,12 @@ permissions:
1111

1212
env:
1313
DOCKER_ENV_REGISTRY: ${{ vars.DOCKER_ENV_REGISTRY }}
14+
DOCKER_ENV_PULL_TAG: ${{ github.sha }}
15+
DOCKER_ENV_PUSH_TAG: ${{ github.ref_name }}
1416

1517
jobs:
1618
tag_dev_image:
1719
runs-on: ubuntu-latest
18-
env:
19-
DOCKER_ENV_PULL_TAG: ${{ github.sha }}
20-
DOCKER_ENV_PUSH_TAG: ${{ github.ref_name }}
2120
steps:
2221
- name: Login to registry
2322
uses: docker/login-action@v3
@@ -29,6 +28,9 @@ jobs:
2928
- name: Clone project
3029
uses: actions/checkout@v4
3130

31+
- name: Init dev env
32+
run: ./docker/env.sh init
33+
3234
- name: Pull dev image
3335
run: |
3436
RETRIES=3

‎.github/workflows/ci_master.yaml‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,12 @@ permissions:
1111

1212
env:
1313
DOCKER_ENV_REGISTRY: ${{ vars.DOCKER_ENV_REGISTRY }}
14+
DOCKER_ENV_PUSH_TAG: ${{ github.sha }}
15+
DOCKER_ENV_BUILD_PLATFORMS: linux/arm64,linux/amd64
1416

1517
jobs:
1618
cache_dev_image:
1719
runs-on: ubuntu-latest
18-
env:
19-
DOCKER_ENV_PUSH_TAG: ${{ github.sha }}
20-
DOCKER_ENV_BUILD_PLATFORMS: linux/arm64,linux/amd64
2120
steps:
2221
- name: Set up multiarch docker builder
2322
uses: docker/setup-buildx-action@v3

‎docs/README.md‎

Lines changed: 62 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,55 @@ Installation in a project is a short manual process, detailed as follows:
2424
Now you're ready to start using `docker-env` in your project. Run `./docker/env.sh --help` for
2525
more information on general usage.
2626

27+
### Multiple environments
28+
29+
You can also use multiple environment images, each with their own Dockerfiles. To do so, simply
30+
prefix each Dockerfile with the corresponding service name, example:
31+
32+
Instead of simply:
33+
34+
`./docker/Dockerfile` -> `dev` service in your project's compose.yaml file
35+
36+
Do:
37+
38+
`./docker/server.Dockerfile` -> `server` service in your project's compose.yaml file
39+
`./docker/app.Dockerfile` -> `app` service in your project's compose.yaml file
40+
41+
### Environment variables
42+
43+
You can customize the following environment variables:
44+
45+
<!-- markdownlint-disable MD013 -->
46+
47+
| var | default | description |
48+
| ------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------- |
49+
| `DOCKER_ENV_PROJECT_NAME` | Repository name | Name of your project (used to generated images and containers) |
50+
| `DOCKER_ENV_PROJECT_DOCKER_DIRECTORY` | `$PWD/docker` | Project directory |
51+
| `DOCKER_ENV_PROJECT_COMPOSE_FILE` | `$DOCKER_ENV_PROJECT_DOCKER_DIRECTORY/compose.yaml` | The dev env compose file, where services are defined |
52+
| `DOCKER_ENV_PROJECT_CACHE_DIRECTORY` | `$PWD/.cache/docker-env` | Where docker-env will store its generated files for your project |
53+
| `DOCKER_ENV_PROJECT_DEFAULT_SERVICE` | dev | Default dev env service to use when unspecified |
54+
| `DOCKER_ENV_BUILD_PLATFORMS` | - | Target platforms when building images |
55+
| `DOCKER_ENV_REGISTRY` | - | Registry where built images will be pulled/pushed from/to |
56+
| `DOCKER_ENV_PULL_TAG` | latest | Image tag to pull from registry |
57+
| `DOCKER_ENV_PUSH_TAG` | latest | Tag built images with value before pushing to registry |
58+
59+
These variables are readonly:
60+
61+
| var | value | description |
62+
| -------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
63+
| `DOCKER_ENV` | true | Only available inside a dev env container |
64+
| `DOCKER_ENV_NAME` | Name of the current service | Only available when running an interactive shell inside a dev env container |
65+
| `DOCKER_ENV_PROJECT_BASE_COMPOSE_FILE` | `$DOCKER_ENV_PROJECT_CACHE_DIRECTORY/base.compose.yaml` | Generated base compose file that **must** be extended by your dev-env service(s) in `$DOCKER_ENV_PROJECT_COMPOSE_FILE` |
66+
67+
<!-- markdownlint-enable MD013 -->
68+
2769
### Recommendations
2870

71+
### Add .cache directory to .gitignore
72+
73+
`docker-env` stores a generated base compose.yaml file for your project in `.cache/docker-env`.
74+
This file should not be commited as it may contain user-specific paths.
75+
2976
#### Alias
3077

3178
You should create an alias for `./docker/env.sh` as it's going to be tedious to type it all the
@@ -46,39 +93,35 @@ export DOCKER_ENV_REGISTRY="ghcr.io/<FOO>" # or any other container registry
4693

4794
#### Local development
4895

49-
Assuming your Docker daemon is running:
96+
Assuming your Docker daemon is running, just run `./docker/env.sh shell` to build/pull images,
97+
create containers, start them and open an interactive shell in the dev env container.
5098

51-
1. `./docker/env.sh init` To pull and/or build the image and create host files.
52-
2. `./docker/env.sh up` To create and start a dev container.
53-
3. `./docker/env.sh shell` To open a shell inside the running dev container.
54-
4. Develop (optionally, attach your editor/IDE to the running dev container).
55-
5. `exit` to close the shell and return to the host computer.
56-
6. `./docker/env.sh down` To stop and remove the running dev container.
99+
> Again, customizing the `$HOME/.config/docker-env/compose.yaml` file will allow you to mount
100+
> your personal configurations in the container for a more familiar environment.
57101
58-
> Again, using a `$HOME/.config/docker-env/compose.yaml` file will allow you to mount your
59-
>  personal configurations in the container for a more familiar environment.
102+
#### CI workflows
60103

61-
#### CI/CD
104+
You can use `./docker/env.sh exec -- COMMAND` to build/pull images, create containers, start
105+
them and execute a command in the dev env container. The `init` and `build` subcommands,
106+
alongside some [environment variables](#environment-variables) can also be used to
107+
build/pull/push/tag dev env images.
62108

63-
1. `./docker/env.sh init` To pull and/or build the image and host files.
64-
2. `./docker/env.sh up` To create and start a dev container.
65-
3. `./docker/env.sh exec COMMAND` To run a command inside the dev container (like running
66-
tests).
67-
4. `./docker/env.sh down` To stop and remove the running dev container.
109+
> You can look at this repo's CI/CD workflows for inspiration
68110
69-
> You can also use the `tag`, `push` and `pull` subcommands to manage your dev image registry
70-
>  versioning.
111+
#### Winding down
112+
113+
When done, you can stop and remove the environment using `./docker/env.sh down`
71114

72115
## Contributors
73116

74117
```shell
75118
git clone git@github.com:logisparte/docker-env.git
76119
cd docker-env
77-
git config --local core.hooksPath "$PWD/hooks"
120+
./scripts/setup.sh # install git hooks
78121
```
79122

80123
> The git hooks will format and lint code before commit, and the git messages will be linted
81-
>  using `commitlint`.
124+
> using `commitlint`.
82125
83126
### Environment
84127

@@ -99,12 +142,6 @@ format dirty files:
99142
./scripts/format.sh
100143
```
101144

102-
To format all files:
103-
104-
```shell
105-
./scripts/format.sh all
106-
```
107-
108145
#### Lint
109146

110147
[ShellCheck](https://github.com/koalaman/shellcheck) is used to analyze shell code.
@@ -114,9 +151,3 @@ code. To analyze dirty files:
114151
```shell
115152
./scripts/lint.sh
116153
```
117-
118-
To analyze all files:
119-
120-
```shell
121-
./scripts/lint.sh all
122-
```

‎templates/user.compose.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
services:
2-
dev:
2+
user:
33
environment:
44
# Configure your personal environment variables here
55
volumes:

0 commit comments

Comments
 (0)