-
Notifications
You must be signed in to change notification settings - Fork 2k
Add instructions for building with docker #434
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
Conversation
34aa845
to
d82bf4b
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Overall, really good. Just a few recommendations and questions.
@@ -0,0 +1,103 @@ | |||
# Develop .NET Core Applications in a Container | |||
|
|||
Docker containers can provide a local .NET Core build environment without having to install anything on your machine. This scenario is also useful if you develop on an operating system that is different than the one you build on. Application building in a container, unlike most container scenarios, can work well for both client and server applications. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You might revise with something like:
Docker containers provide a local .NET Core build environment without additional installation on your machine. This scenario is also useful if your development operating system differs from your build operating system. Application building in a container works well for both client and server applications, unlike most container scenarios.
|
||
Docker containers can provide a local .NET Core build environment without having to install anything on your machine. This scenario is also useful if you develop on an operating system that is different than the one you build on. Application building in a container, unlike most container scenarios, can work well for both client and server applications. | ||
|
||
The goal isn't to produce a Docker image, but build binaries from source on your disk. After running a build in this way, the binaries will be on your disk, not in a Docker container. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You might revise with something like:
The goal is to build binaries from your disk source, not to produce a Docker image. After a successful build, the binaries will be on your disk, not in a Docker container.
|
||
The goal isn't to produce a Docker image, but build binaries from source on your disk. After running a build in this way, the binaries will be on your disk, not in a Docker container. | ||
|
||
There are a few ways to use Docker for containerized builds. For simple scenarios, you can use a combination of docker run and volume mounting, as is done with [Develop .NET Core Applications in a Container](dotnet-docker-dev-in-container.md). For more complex scenarios, you need to first build a custom Dockerfile or build to a stage of an existing Dockerfile, as is done with [Running .NET Core Unit Tests with Docker](dotnet-docker-unit-testing.md). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You might tighten up with something like:
For simple Docker containerized build scenarios, use a combination of docker run and volume mounting, as is done with Develop .NET Core Applications in a Container. For complex Docker containerized build scenarios, first build a custom Dockerfile, or build to an existing Dockerfile stage, as is done with Running .NET Core Unit Tests with Docker.
## Build .NET source with Docker run | ||
|
||
You can build your application with the .NET Core SDK Docker image. You will find built assets in the `out` directory. | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
May want to revise with something like:
Build your application with the .NET Core SDK Docker image. Built assets will be in the out
directory.
|
||
## Requirements | ||
|
||
It is recommended that you add a [Directory.Build.props](Directory.Build.props) file to your project to use different `obj` and `bin` folders for local and container use, to avoid conflicts between them. You should delete your existing obj and bin folders before making this change. You can also use `dotnet clean` for this purpose. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If this is a requirement, should it be recommended or prescribed? Is the conflict between the folders or the containers?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
between container and local.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this might be more clear:
To avoid conflicts between container usage and your local environment, you need to use a different set of obj
and bin
folders for each environment.
Make this change with the following steps:
- Delete your existing obj and bin folders manually or use
dotnet clean
. - Add a Directory.Build.props file to your project to use a different set of
obj
andbin
folders for your local and container environments.
dotnet dotnetapp.dll | ||
``` | ||
|
||
> Note: Application built for a different .NET Core version that you have on your machine or for a specific runtime (`-r` argument) may or may not run on your machine. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Application -> Applications
Might consider something like:
Note: Applications built for a different .NET Core version on your machine, or for a specific runtime (-r
argument) might not run on your machine.
## Build .NET source with Docker build and extract binaries with Docker run | ||
|
||
More complex applications may require more complex builds than `dotnet publish` on its own provides. This may be accomplished with [multi-stage build](https://docs.docker.com/develop/develop-images/multistage-build/) or other approaches. The following commands demonstrate how to enable this scenario. The instructions assume that you are in the root of the repository. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You might revise with:
Complex application build requirements may need more than dotnet publish
provides. A multi-stage build approach can enable a complex build scenario. demonstrated by the following example: The instructions assume that you are in the root of the repository.
dotnet dotnetapp.dll | ||
``` | ||
|
||
> Note: Application built for a different .NET Core version that you have on your machine or for a specific runtime (`-r` argument) may or may not run on your machine. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Application -> Applications
Might consider something like:
Note: Applications built for a different .NET Core version on your machine, or for a specific runtime (-r argument) might not run on your machine.
|
||
More complex applications may require more complex builds than `dotnet publish` on its own provides. This may be accomplished with [multi-stage build](https://docs.docker.com/develop/develop-images/multistage-build/) or other approaches. The following commands demonstrate how to enable this scenario. The instructions assume that you are in the root of the repository. | ||
|
||
Build the docker image. The assumption in this example is that an exiting [Dockerfile](Dockerfile) is being used, with a particular stage being targeted. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You might use something like:
This example assumes an exiting Dockerfile is being used, with a particular stage target.
docker run --rm -v c:\git\dotnet-docker\samples\dotnetapp\out:c:\app\out -w \app dotnetapp:publish cmd /C "copy /Y dotnetapp\out out" | ||
``` | ||
|
||
You can now run the application on your local machine, assuming you are at the root of the repository: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Tighten with something like:
Run the application on your local machine, assuming you are at the root of the repository:
@@ -0,0 +1,103 @@ | |||
# Develop .NET Core Applications in a Container |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should this be Build .NET Core Applications in a Container?
OK. I think this is done ...
|
May want to change: On your local machine, you can use either .NET Core 2.1 or .NET Core 2.0 projects to try out these instructions. |
## More Samples | ||
|
||
* [.NET Core Docker Samples](../README.md) | ||
* [.NET Framework Docker Samples](https://github.com/microsoft/dotnet-framework-docker-samples/) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In "Build .NET Core Applications for ARM32 and Raspberry Pi with Docker" under "Building the Sample with Docker" section, this change might help with clarity.
"This sample must be built on a 64-bit operating system, as the .NET Core SDK is not currently supported on ARM32."
Also, line 33: Might consider: "Next, pull the image on an ARM32 device (like a Pi) from the recently pushed registry."
And line 35: You might simplify with " Note: Change the password location and the user account ("rich" and "richlander") example values in your environment. "
Line 46:
First, docker login
to Azure Container Registry. For more information, see Push Docker Images to Azure Container Registry.
|
||
## Requirements | ||
|
||
It is recommended that you add a [Directory.Build.props](Directory.Build.props) file to your project to use different `obj` and `bin` folders for local and container use, to avoid conflicts between them. Delete your existing obj and bin folders before making this change. You can also use `dotnet clean` for this purpose. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The current Directory.Build.props is not ideal with the 2.0-sdk image because it doesn't have the DOTNET_RUNNING_IN_CONTAINER variable set. This is going to lead to some confusion.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Now that I merged everything into one doc ... the first two dotnet-watch scenarios require 2.1. The build scenario can work with 2.0 w/o issue. So, we either say it is all 2.1 or back-port env variables to 2.0. I suggest the latter. Thoughts?
samples/README.md
Outdated
|
||
## Develop .NET Core Apps in a Container | ||
|
||
* [Build .NET Core Applications](dotnetapp/dotnet-docker-build-with-container.md) - This sample shows how to build .NET Core applications with Docker without the need to create a Dockerfile or install the .NET Core SDK. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I have some concerns about the differentiation between the build and develop samples. I can see this causing some confusion for newcomers. Part of me thinks the two samples could be combined....IDK.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Agreed. Merged.
docker run --rm -v c:\git\dotnet-docker\samples\dotnetapp:c:\app -w c:\app\dotnetapp microsoft/dotnet:2.0-sdk dotnet publish -c release -o out | ||
``` | ||
|
||
You can now run the application on your local machine, assuming you are at the root of the repository: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What is the attraction to running locally? If you depend on a shared framework, then you would need that installed locally. You also note that there are issues with framework dependent deployments as well. Would it be better to show how to include the steps to run the app in a container?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Agreed. Removed.
dotnet dotnetapp.dll | ||
``` | ||
|
||
> Note: Application built for a different .NET Core version that you have on your machine or for a specific runtime (`-r` argument) may or may not run on your machine. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In "Deploy ASP.NET Core Applications to Azure Container Instances", line 3, - use -> used. ACI is a great option for application testing and can also be used for production deployment (not covered here).
Also, you might remove the second "sample" here on line 3: "These instructions are based on the ASP.NET Core Docker Sample."
Line 19: You might simplify with " Note: Change the password location and the user account ("rich" and "richlander") example values in your environment. "
Might be tighter with something like this on line 29: "First, "admin-enable" your session, an ACR credentials access prerequisite for the subsequent command."
A little tighter with something like this on line 35: "Now login to ACR via the docker cli, an ACR push prerequisite:"
Might be more clear with something like this on line 58: "During deployment, you'll need to enter your password. Type or copy/paste it in. Get your password beforehand from the following command:"
Might be a little tighter with something like this on line 78: "When these containers aren't needed, delete the resource group to reclaim all exercise container resources."
I agree with you.
Regards,
John
________________________________
From: Rich Lander <[email protected]>
Sent: Saturday, March 24, 2018 12:57:20 PM
To: dotnet/dotnet-docker
Cc: John Alexander; Comment
Subject: Re: [dotnet/dotnet-docker] Add instructions for building with docker (#434)
@richlander commented on this pull request.
________________________________
In samples/dotnetapp/dotnet-docker-build-with-container.md<https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fdotnet%2Fdotnet-docker%2Fpull%2F434%23discussion_r176915704&data=02%7C01%7Cjohn.alexander%40microsoft.com%7C80a0a12c446c4520aec308d591b0b126%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636575110431404007&sdata=8hhQrVMW5juXOQ1Oi9205R%2FVdXRalrqMRzb2pkUhOQw%3D&reserved=0>:
+
+You can use the [.NET Core SDK image](https://hub.docker.com/r/microsoft/dotnet/) for your build environment. For more complex environments, you can build your own image and re-use the same pattern demonstrated in the following instructions. [`docker cp`](https://docs.docker.com/engine/reference/commandline/cp/) can be used to copy built binaries from an image. That case is not documented here.
+
+## Getting the sample
+
+The easiest way to get the sample is by cloning the samples repository with [git](https://git-scm.com/downloads), using the following instructions:
+
+```console
+git clone https://github.com/dotnet/dotnet-docker/
+```
+
+You can also [download the repository as a zip](https://github.com/dotnet/dotnet-docker/archive/master.zip).
+
+## Requirements
+
+It is recommended that you add a [Directory.Build.props](Directory.Build.props) file to your project to use different `obj` and `bin` folders for local and container use, to avoid conflicts between them. Delete your existing obj and bin folders before making this change. You can also use `dotnet clean` for this purpose.
Now that I merged everything into one doc ... the first two dotnet-watch scenarios require 2.1. The build scenario can work with 2.0 w/o issue. So, we either say it is all 2.1 or back-port env variables to 2.0. I suggest the latter. Thoughts?
—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub<https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fdotnet%2Fdotnet-docker%2Fpull%2F434%23discussion_r176915704&data=02%7C01%7Cjohn.alexander%40microsoft.com%7C80a0a12c446c4520aec308d591b0b126%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636575110431404007&sdata=8hhQrVMW5juXOQ1Oi9205R%2FVdXRalrqMRzb2pkUhOQw%3D&reserved=0>, or mute the thread<https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FAElQwR9fP2ZJqkTUOAWEXiO-SyAGe_XFks5thokAgaJpZM4Swjvh&data=02%7C01%7Cjohn.alexander%40microsoft.com%7C80a0a12c446c4520aec308d591b0b126%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636575110431404007&sdata=U0q%2BY2QLwotnJW5fkd%2BcGXEpnWV652ZdKnjMt9kDHnw%3D&reserved=0>.
|
Like the developing in a docker container topic but specifically for building.