docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

dev envs refresh (#15989) 

* dev envs refresh

* feedback

* clarification

* Update desktop/dev-environments/set-up.md

Co-authored-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

Co-authored-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
This commit is contained in:
Allie Sadler 2022-11-01 15:54:36 +00:00 committed by GitHub
parent a2f0ccaa4f
commit 83e227e018
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 258 additions and 189 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
_data/toc.yaml
View File

@ -1310,11 +1310,13 @@ manuals:
- path: /desktop/dev-environments/
title: Overview
- path: /desktop/dev-environments/create-dev-env/
title: Create a simple dev environment
- path: /desktop/dev-environments/create-compose-dev-env/
title: Create an advanced dev environment
title: Launch a dev environment
- path: /desktop/dev-environments/set-up/
title: Set up a dev environment
- path: /desktop/dev-environments/share/
title: Distribute your dev environment
- path: /desktop/dev-environments/dev-cli/
title: Use the docker dev CLI plugin
- sectiontitle: Extensions (Beta)
section:
- path: /desktop/extensions/

131
desktop/dev-environments/create-compose-dev-env.md
View File

@ -1,131 +0,0 @@
---
description: Dev Environments
keywords: Dev Environments, share, collaborate, local, compose
title: Create an advanced dev environment
---
Create an advanced dev environment such as a microservice with a server, proxy and DB.
As with a simple dev environment, you can create a more advanced dev environment from a:
- Git repository
- Branch or tag of a Git repository
- Subfolder of a Git repository
- Local folder
> **Note**
>
> When cloning a Git repository using SSH, ensure you've added your SSH key to the ssh-agent. To do this, open a terminal and run `ssh-add <path to your private ssh key>`.
## Create a Compose Dev Environment
The example below, taken from the `compose-dev-env` project from the [Docker Samples](https://github.com/dockersamples/compose-dev-env){:target="_blank" rel="noopener" class="_"} GitHub repository, demonstrates how to create a Compose Dev Environment from a Git repository.
>Note
>
>Currently, Dev Environments is not able to detect the main language of the subdirectory. You need to define your own base image or compose services in a `compose-dev.yaml` located in your subdirectory.
>
>For more information on how to configure, see the [React application with a Spring backend and a MySQL database sample](https://github.com/docker/awesome-compose/tree/master/react-java-mysql) or the [Go server with an Nginx proxy and a Postgres database sample](https://github.com/docker/awesome-compose/tree/master/nginx-golang-postgres).
1. From **Dev Environments**, select **Create**. The **Create a Dev Environment** dialog displays.
2. Click **Get Started** and then copy `https://github.com/dockersamples/compose-dev-env.git` and add it to the **Enter the Git Repository** field with **Existing Git repo** as the source.
3. Click **Continue**. This initializes the project, clones the Git code, and builds the Compose application. This:
- Builds local images for services that are defined in the Compose file
- Pulls images required for other services
- Creates volumes and networks
- Starts the Compose stack
Once your application is up and running, you can check by opening [http://localhost:8080](http://localhost:8080) in your browser.
The time taken to start the Compose application depends on how your application is configured, whether the images have been built, and the number of services you have defined, for example.
Note that VS Code doesn't open directly, unlike a simple Dev Environment, as there are multiple services configured. You can hover over a service and then click on the **Open in VS Code** button to open a specific service in VS Code. This stops the existing container and creates a new container which allows you to develop and update your service in VS Code.
You can now update your service and test it against your Compose application.
## Set up your own dev environment
>**Changes to Dev Environments with Docker Desktop 4.13**
>
>Docker has simplified how you configure your dev environment project. All you need to get started is a `compose-dev.yaml` file. If you have an existing project with a `.docker/` folder this is automatically migrated the next time you launch.
>
> If you are using `.docker/docker-compose.yaml`, we move it to `../compose-dev.yaml`.
>If you are using `.docker/config.json`, we create a `../compose-dev.yaml` file with a single service named "app”. It is configured to use the image or Dockerfile referenced in the JSON as a starting point.
{: .important}
To set up a dev environment, there are additional configuration steps to tell Docker Desktop how to build, start, and use the right image for your services.
Dev Environments use an `compose-dev.yaml` file located in the at the root of your project. This file allows you to define the image required for a dedicated service, the ports you'd like to expose, along with additional configuration options dedicated to Dev Environments coming in the future.
Take a detailed look at the `compose-dev.yaml` file used in the [compose-dev-env](https://github.com/dockersamples/compose-dev-env/blob/main/.docker/docker-compose.yaml){:target="_blank" rel="noopener" class="_"} sample project.
```yaml
version: "3.7"
services:
backend:
build:
context: backend
target: development
secrets:
- db-password
depends_on:
- db
db:
image: mariadb
restart: always
healthcheck:
test: [ "CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "--silent" ]
interval: 3s
retries: 5
start_period: 30s
secrets:
- db-password
volumes:
- db-data:/var/lib/mysql
environment:
- MYSQL_DATABASE=example
- MYSQL_ROOT_PASSWORD_FILE=/run/secrets/db-password
expose:
- 3306
proxy:
build: proxy
ports:
- 8080:80
depends_on:
- backend
volumes:
db-data:
secrets:
db-password:
file: db/password.txt
```
In the yaml file, the build context `backend` specifies that that the container should be built using the `development` stage (`target` attribute) of the Dockerfile located in the `backend` directory (`context` attribute)
The `development` stage of the Dockerfile is defined as follows:
```dockerfile
FROM golang:1.16-alpine AS build
WORKDIR /go/src/github.com/org/repo
COPY . .
RUN go build -o server .
FROM build AS development
RUN apk update \
&& apk add git
CMD ["go", "run", "main.go"]
FROM alpine:3.12
EXPOSE 8000
COPY --from=build /go/src/github.com/org/repo/server /server
CMD ["/server"]
```
The `development`target uses a `golang:1.16-alpine` image with all dependencies you need for development. You can start your project directly from VS Code and interact with the others applications or services such as the database or the frontend.
In the example, the Docker Compose files are the same. However, they could be different and the services defined in the main Compose file may use other targets to build or directly reference other images.
## What's next?
Learn how to [distribute your dev environment](share.md)

56
desktop/dev-environments/create-dev-env.md
View File

@ -1,22 +1,36 @@
---
description: Dev Environments
keywords: Dev Environments, share, collaborate, local
title: Create a simple dev environment
title: Launch a dev environment
redirect_from:
- /desktop/dev-environments/create-compose-dev-env/
---
You can create a dev environment from a:
You can launch a dev environment from a:
- Git repository
- Branch or tag of a Git repository
- Subfolder of a Git repository
- Local folder
This did not conflict with any of the local files or local tooling set up on your host.
This does not conflict with any of the local files or local tooling set up on your host.
## Create a dev environment from a Git repository
## Prerequisites
The simplest way to get started with Dev Environments is to create a new environment by cloning the Git repository of the project you are working on.
Dev Environments is available as part of Docker Desktop 3.5.0 release. Download and install **Docker Desktop 3.5.0** or higher:
For example, create a new Dev Environment using the simple `single-dev-env` project from the [Docker Samples](https://github.com/dockersamples/single-dev-env){:target="_blank" rel="noopener" class="_"} GitHub repository.
- [Docker Desktop](../release-notes.md)
To get started with Dev Environments, you must also install the following tools and extension on your machine:
- [Git](https://git-scm.com){:target="_blank" rel="noopener" class="_"}. Make sure add Git to your PATH if you're a Windows user.
- [Visual Studio Code](https://code.visualstudio.com/){:target="_blank" rel="noopener" class="_"}
- [Visual Studio Code Remote Containers Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers){:target="_blank" rel="noopener" class="_"}
> **Note**
>
> After Git is installed, restart Docker Desktop. Select **Quit Docker Desktop**, and then start it again.
## Launch a dev environment from a Git repository or subdirectory.
> **Note**
>
@ -55,22 +69,22 @@ fi
</div>
</div>
To create a dev environment:
To launch a dev environment:
1. From **Under Dev Environments** in Docker Dashboard, click **Create**. The **Create a Dev Environment** dialog displays.
2. Select **Get Started** and then copy `https://github.com/dockersamples/single-dev-env.git` and add it to the **Enter the Git Repository** field with **Existing Git repo** as the source.
1. From **Under Dev Environments** in Docker Dashboard, select **Create**. The **Create a Dev Environment** dialog displays.
2. Select **Get Started** and then copy your Git repository link and add it to the **Enter the Git Repository** field with **Existing Git repo** as the source.
3. Select **Continue**.
This detects the main language of your repository, clones the Git code inside a volume, determines the best image for your Dev Environment, and opens VS Code inside the Dev Environment container.
This detects the main language of your repository, clones the Git code inside a volume, determines the best image for your dev environment, and opens VS Code inside the dev environment container.
4. Hover over the container and select **Open in VS Code** to start working. You can also open a terminal in VS Code, and use Git to push or pull code to your repository, or switch between branches and work as you would normally.
5. To launch the application, run the command `make run` in your terminal. This opens an http server on port 8080. Open [http://localhost:8080](http://localhost:8080) in your browser to see the running application.
## Create a dev environment from a specific branch or tag
## Launch from a specific branch or tag
You can create a dev environment from a specific branch (for example, a branch corresponding to a Pull Request) or a tag by adding `@mybranch` or `@tag` as a suffix to your Git URL:
You can launch a dev environment from a specific branch, for example a branch corresponding to a Pull Request, or a tag by adding `@mybranch` or `@tag` as a suffix to your Git URL:
`https://github.com/dockersamples/single-dev-env@mybranch`
@ -80,30 +94,30 @@ You can create a dev environment from a specific branch (for example, a branch c
Docker then clones the repository with your specified branch or tag.
## Create a dev environment from a subdirectory of a Git repository
## Launch from a subfolder of a Git repository
>Note
>
>Currently, Dev Environments is not able to detect the main language of the subdirectory. You need to define your own base image or services in a `compose-dev.yaml`file located in your subdirectory. For more information on how to configure, see the [React application with a Spring backend and a MySQL database sample](https://github.com/docker/awesome-compose/tree/master/react-java-mysql) or the [Go server with an Nginx proxy and a Postgres database sample](https://github.com/docker/awesome-compose/tree/master/nginx-golang-postgres).
1. From **Dev Environments** in Docker Dashboard, click **Create**. The **Create a Dev Environment** dialog displays.
1. From **Dev Environments** in Docker Dashboard, select **Create**. The **Create a Dev Environment** dialog displays.
2. Select **Get Started** and then copy your Git subfolder link into the **Enter the Git Repository** field with **Existing Git repo** as the source.
3. Select **Continue**.
This clones the Git code inside a volume, determines the best image for your Dev Environment, and opens VS Code inside the Dev Environment container.
This clones the Git code inside a volume, determines the best image for your dev environment, and opens VS Code inside the dev environment container.
4. Hover over the container and select **Open in VS Code** to start working. You can also open a terminal in VS Code, and use Git to push or pull code to your repository, or switch between branches and work as you would normally.
5. To launch the application, run the command `make run` in your terminal. This opens an http server on port 8080. Open [http://localhost:8080](http://localhost:8080) in your browser to see the running application.
## Create a dev environment from a local folder
## Launch from a local folder
1. From **Dev Environments** in Docker Dashboard, click **Create**. The **Create a Dev Environment** dialog displays.
1. From **Dev Environments** in Docker Dashboard, select **Create**. The **Create a Dev Environment** dialog displays.
2. Select **Get Started** and then choose **Local Folder** as the source.
3. Select **Select directory** to open the root of the code that you would like to work on.
3. Next to **Select your local directory** field, select **Select** to open the root of the code that you would like to work on.
4. Select **Continue**.
This detects the main language of your local folder, creates a Dev Environment using your local folder, and bind-mounts your local code in the Dev Environment. It then opens VS Code inside the Dev Environment container.
This detects the main language of your local folder, creates a dev environment using your local folder, and bind-mounts your local code in the dev environment. It then opens VS Code inside the dev environment container.
> **Note**
>
@ -111,4 +125,6 @@ Docker then clones the repository with your specified branch or tag.
## What's next?
Learn how to [distribute your dev environment](share.md)
Learn how to:
- [Set up a dev environment](set-up.md)
- [Distribute your dev environment](share.md)

116
desktop/dev-environments/dev-cli.md Normal file
View File

@ -0,0 +1,116 @@
---
description: Set up a dev Environments
keywords: Dev Environments, share, collaborate, local, set up
title: Use the docker dev CLI plugin
---
Use the new `docker dev` CLI plugin to get the full Dev Environments experience from the terminal in addition to the Dashboard.
It is available with [Docker Desktop 4.13.0 or later](../release-notes.md).
### Usage
```
docker dev [OPTIONS] COMMAND
```
### Commands
| Command | Description |
|:---------------------|:-----------------------------------------|
| `check` | Check Dev Environments |
| `create` | Create a new dev environment |
| `list` | Lists all dev environments |
| `logs` | Traces logs from a dev environment |
| `open` | Open Dev Envrionment with the IDE |
| `rm` | Removes a dev environment |
| `start` | Starts a dev environment |
| `stop` | Stops a dev environment |
| `version` | Shows the Docker Dev version information |
### `docker dev check`
#### Usage
`docker dev check [OPTIONS]`
#### Options
| Name, shorthand | Description |
|:---------------------|:------------------------------------|
| `--format`,`-f` | Format the output. |
### `docker dev create`
#### Usage
`docker dev create [OPTIONS] REPOSITORY_URL`
#### Options
| Name, shorthand | Description |
|:---------------------|:----------------------------------------------------------|
| `--detach`,`-d` | Detach creates a Dev Env without attaching to it's logs. |
| `--open`,`-o` | Open IDE after a successful creation |
### `docker dev list`
#### Usage
`docker dev list [OPTIONS]`
#### Options
| Name, shorthand | Description |
|:---------------------|:------------------------------|
| `--format`,`-f` | Format the output |
| `--quiet`,`-q` | Only show dev environments names |
### `docker dev logs`
#### Usage
`docker dev logs [OPTIONS] DEV_ENV_NAME`
### `docker dev open`
#### Usage
`docker dev open DEV_ENV_NAME CONTAINER_REF [OPTIONS]`
#### Options
| Name, shorthand | Description |
|:---------------------|:----------------------|
| `--editor`,`-e` | Editor. |
### `docker dev rm`
#### Usage
`docker dev rm DEV_ENV_NAME`
### `docker dev start`
#### Usage
`docker dev start DEV_ENV_NAME`
### `docker dev stop`
#### Usage
`docker dev stop DEV_ENV_NAME`
### `docker dev version`
#### Usage
`docker dev version [OPTIONS]`
#### Options
| Name, shorthand | Description |
|:---------------------|:----------------------------------------------|
| `--format`,`-f` | Format the output. |
| `--short`,`-s` | Shows only Docker Dev's version number. |

44
desktop/dev-environments/index.md
View File

@ -11,48 +11,26 @@ Dev Environments lets you create a configurable developer environment with all t
It uses tools built into code editors that allows Docker to access code mounted into a container rather than on your local host. This isolates the tools, files and running services on your machine allowing multiple versions of them to exist side by side.
You can use Dev Environments through the intuitive GUI in Docker Dashboard or straight from you terminal with the new [`docker dev` CLI plugin](dev-cli.md).
![Dev environment intro](../images/dev-env.PNG){:width="700px"}
## How does it work?
>**Changes to Dev Environments with Docker Desktop 4.13**
>
>Docker has simplified how you configure your dev environment project. All you need to get started is a `compose-dev.yaml` file. If you have an existing project with a `.docker/` folder this is automatically migrated the next time you launch.
{: .important}
![Dev environment intro](../images/dev-env.PNG){:width="700px"}
Dev Environments is powered by [Docker Compose](/compose/). This allows Dev Environments to take advantage of all the benefits and features of Compose whilst adding an intuitive GUI where you can launch environments with the click of a button.
## Prerequisites
Every dev environment you want to run needs a `compose-dev.yaml` file which configures your application's services and lives in your project directory. You don't need to be an expert in Docker Compose or write a `compose-dev.yaml` file from scratch as Dev Environments creates a starter `compose-dev.yaml` files based on the main language in your project.
Dev Environments is available as part of Docker Desktop 3.5.0 release. Download and install **Docker Desktop 3.5.0** or higher:
- [Docker Desktop](../release-notes.md)
To get started with Dev Environments, you must also install the following tools and extension on your machine:
- [Git](https://git-scm.com){:target="_blank" rel="noopener" class="_"}
- [Visual Studio Code](https://code.visualstudio.com/){:target="_blank" rel="noopener" class="_"}
- [Visual Studio Code Remote Containers Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers){:target="_blank" rel="noopener" class="_"}
### Add Git to your PATH on Windows
If you have already installed Git, and it's not detected properly, run the following command to check whether you can use Git with the CLI or PowerShell:
`$ git --version`
If it doesn't detect Git as a valid command, you must reinstall Git and ensure you choose the option **Git from the command line...** or the **Use Git and optional Unix tools...** on the **Adjusting your PATH environment** step.
![Windows add Git to path](../images/dev-env-gitbash.png){:width="300px"}
> **Note**
>
> After Git is installed, restart Docker Desktop. Select **Quit Docker Desktop**, and then start it again.
## Known issues
The following section lists known issues and workarounds:
1. When sharing a dev environment between Mac and Windows, the VS Code terminal may not function correctly in some cases. To work around this issue, use the Exec in CLI option in the Docker Dashboard.
You can also use the many [sample dev environments](https://github.com/docker/awesome-compose) as a starting point for how to integrate different services. Alternatively, see [Set up a dev environment](set-up.md) for more information.
## What's next?
Learn how to:
- [Create a simple dev environment](create-dev-env.md)
- [Create an advanced dev environment](create-compose-dev-env.md)
- [Launch a dev environment](create-dev-env.md)
- [Set up a dev environment](set-up.md)
- [Distribute your dev environment](share.md)

88
desktop/dev-environments/set-up.md Normal file
View File

@ -0,0 +1,88 @@
---
description: Set up a dev Environments
keywords: Dev Environments, share, collaborate, local, set up
title: Set up a dev environment
---
## Set up your own dev environment
>**Changes to Dev Environments with Docker Desktop 4.13**
>
>Docker has simplified how you configure your dev environment project. All you need to get started is a `compose-dev.yaml` file. If you have an existing project with a `.docker/` folder this is automatically migrated the next time you launch.
>
> If you are using `.docker/docker-compose.yaml`, we move it to `../compose-dev.yaml`.
>If you are using `.docker/config.json`, we create a `../compose-dev.yaml` file with a single service named "app”. It is configured to use the image or Dockerfile referenced in the JSON as a starting point.
{: .important}
To set up a dev environment, there are additional configuration steps to tell Docker Desktop how to build, start, and use the right image for your services.
Dev Environments use an `compose-dev.yaml` file located at the root of your project. This file allows you to define the image required for a dedicated service, the ports you'd like to expose, along with additional configuration options.
The following is an example `compose-dev.yaml` file.
```yaml
version: "3.7"
services:
backend:
build:
context: backend
target: development
secrets:
- db-password
depends_on:
- db
db:
image: mariadb
restart: always
healthcheck:
test: [ "CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "--silent" ]
interval: 3s
retries: 5
start_period: 30s
secrets:
- db-password
volumes:
- db-data:/var/lib/mysql
environment:
- MYSQL_DATABASE=example
- MYSQL_ROOT_PASSWORD_FILE=/run/secrets/db-password
expose:
- 3306
proxy:
build: proxy
ports:
- 8080:80
depends_on:
- backend
volumes:
db-data:
secrets:
db-password:
file: db/password.txt
```
In the yaml file, the build context `backend` specifies that that the container should be built using the `development` stage (`target` attribute) of the Dockerfile located in the `backend` directory (`context` attribute)
The `development` stage of the Dockerfile is defined as follows:
```dockerfile
FROM golang:1.16-alpine AS build
WORKDIR /go/src/github.com/org/repo
COPY . .
RUN go build -o server .
FROM build AS development
RUN apk update \
&& apk add git
CMD ["go", "run", "main.go"]
FROM alpine:3.12
EXPOSE 8000
COPY --from=build /go/src/github.com/org/repo/server /server
CMD ["/server"]
```
The `development` target uses a `golang:1.16-alpine` image with all dependencies you need for development. You can start your project directly from VS Code and interact with the others applications or services such as the database or the frontend.
In the example, the Docker Compose files are the same. However, they could be different and the services defined in the main Compose file may use other targets to build or directly reference other images.
## What's next?
Learn how to [distribute your dev environment](share.md)

2
desktop/previous-versions/3.x-mac.md
View File

@ -24,7 +24,7 @@ This page contains release notes for Docker Desktop for Mac 3.x.
### New
- **Dev Environments**: You can now create a Dev Environment from your local Git repository. For more information, see [Create a Dev Environment from a local folder](../dev-environments/create-dev-env.md#create-a-dev-environment-from-a-local-folder).
- **Dev Environments**: You can now create a Dev Environment from your local Git repository.
- **Volume Management**: You can now sort volumes by the name, the date created, and the size of the volume. You can also search for specific volumes using the **Search** field. For more information, see [Explore volumes](../use-desktop/volumes.md).
### Upgrades

2
desktop/previous-versions/3.x-windows.md
View File

@ -23,7 +23,7 @@ This page contains release notes for Docker Desktop for Windows 3.x.
### New
- **Dev Environments**: You can now create a Dev Environment from your local Git repository. For more information, see [Create a Dev Environment from a local folder](../dev-environments/create-dev-env.md#create-a-dev-environment-from-a-local-folder).
- **Dev Environments**: You can now create a Dev Environment from your local Git repository.
- **Volume Management**: You can now sort volumes by the name, the date created, and the size of the volume. You can also search for specific volumes using the **Search** field. For more information, see [Explore volumes](../use-desktop/volumes.md).
### Upgrades