Add Dockerize and ASP.NET Core doc #1681

kendrahavens · 2017-02-15T19:12:24Z

Proposed changes

Add "Dockerize an ASP.NET Core app" documentation to the Docker engine examples section.

This doc takes the user through adding a Dockerfile and .dockerignore file to a simple ASP.NET Core application. It includes both Linux and Windows Container options for writing the Dockerfile. It then instructs the user on how to build and run the Docker container and view it in the browser.

mdlinville

Awesome! I left a few notes. Please let me know if I have misunderstood anything or if you have questions about the feedback.

mdlinville · 2017-02-15T21:05:39Z

engine/examples/dotnetcore.md

+---
+description: Create a Docker image by layering your ASP.NET Core app on debian for Linux Containers or with Windows Nano Server containers using a Dockerfile.
+keywords: docker, dockerize, dockerizing, dotnet, .NET, Core, article, example, platform, installation, containers, images, image, dockerfile, build, asp.net, asp.net core
+title: Dockerizing a .NET Application


Please use sentence case (so no caps on "Application")

mdlinville · 2017-02-15T21:06:25Z

engine/examples/dotnetcore.md

+
+This example demonstrates how to dockerize an ASP.NET Core application.
+
+> **Note:** This example assumes you already have a published ASP.NET Core app on your machine. If you are new to ASP.NET you can follow a [simple tutorial](https://www.asp.net/get-started) to initialize a project.


Maybe put this into a prerequisites section instead of a note?

mdlinville · 2017-02-15T21:06:49Z

engine/examples/dotnetcore.md

+
+## Why build ASP.NET Core?
+- [Open-source](https://github.com/aspnet/home)
+- Develop and run your ASP.NET Core apps cross-platform on Windows, Mac and Linux


s/Mac/macOS

mdlinville · 2017-02-15T21:07:21Z

engine/examples/dotnetcore.md

+- [Open-source](https://github.com/aspnet/home)
+- Develop and run your ASP.NET Core apps cross-platform on Windows, Mac and Linux
+- Great for modern cloud-based apps, such as web apps, IoT apps and mobile backends 
+- ASP.NET Core apps can run on [.NET Core](https://www.microsoft.com/net/core/platform) or on the full [.NET Framework](https://www.microsoft.com/net/framework)


Please try to wrap lines longer than 80 characters for easier diffing later

mdlinville · 2017-02-15T21:08:08Z

engine/examples/dotnetcore.md

+- Develop and run your ASP.NET Core apps cross-platform on Windows, Mac and Linux
+- Great for modern cloud-based apps, such as web apps, IoT apps and mobile backends 
+- ASP.NET Core apps can run on [.NET Core](https://www.microsoft.com/net/core/platform) or on the full [.NET Framework](https://www.microsoft.com/net/framework)
+- Architected to provide an optimized development framework for apps that are deployed to the cloud or run on-premises


Maybe s/Architected/Designed

s/on-premises/on-premise

mdlinville · 2017-02-15T21:10:54Z

engine/examples/dotnetcore.md

+!published
+```
+
+> **Note:** If you are using Windows Containers on [Docker for Windows](https://docs.docker.com/docker-for-windows/) be sure to check that you are properly switched to Windows Containers. Do this by opening the system tray up arrow and right clicking on the Docker whale icon for a popup menu. In the popup menu make sure you select 'Switch to Windows Containers'. 


Maybe link to the Docker for Windows instructions for doing this?

mdlinville · 2017-02-15T21:11:57Z

engine/examples/dotnetcore.md

+1. Open the command prompt and navigate to your project folder.
+2. Use the following commands to build and run your Docker image:
+
+```console


This belongs under step 2. By the way, for numbered lists, everything lines up better if you put two spaces between the dot and the first word, for single-letter bullets. This way, the codeblock (or sub-list or image or whatever) is aligned on the tab stops. Jekyll is very picky about indentation.

Great tip! I noticed my indented code blocks weren't recognized in the netlify preview. I'll add two spaces in between my numbered lists and indent the code block.

mdlinville · 2017-02-15T21:12:50Z

engine/examples/dotnetcore.md

+> **Note:** If you are using Windows Containers on [Docker for Windows](https://docs.docker.com/docker-for-windows/) be sure to check that you are properly switched to Windows Containers. Do this by opening the system tray up arrow and right clicking on the Docker whale icon for a popup menu. In the popup menu make sure you select 'Switch to Windows Containers'. 
+
+## Build and run the Docker image
+1. Open the command prompt and navigate to your project folder.


Don't you already have the command prompt open? You already told them to run dotnet restore and stuff.

It is possible they ran these commands from Visual Studio or VS Code. I'll change it to "In the command prompt." Great point!

mdlinville · 2017-02-15T21:14:02Z

engine/examples/dotnetcore.md

+docker run -d -p 80:80 aspnetapp
+```
+
+## View your web page running from your container


This is a bit awkardly worded. Lots of "your". Maybe "View the app's live web page" or something like that?

mdlinville · 2017-02-15T21:14:36Z

engine/examples/dotnetcore.md

+```
+
+## View your web page running from your container
+* If you are using a Linux container you can simply browse to http://localhost:80 to access your app in a web browser.


s/you can simply/,

Also you need to linkify the URL manually. It doesn't get automatically transformed. Looks prettier with a trailing slash too.

friism · 2017-02-15T23:12:01Z

This doesn't look good to me. I'm copy-pasting a critique I've offered to assorted others previously.

The basic problem is that the tutorial assumes users build the .NET app outside of Docker. This means the tutorial requires installing a bunch of random software on the machine for the project to build (in this case VS, .NET Core and Bower and Gulp - in addition to Docker). This nullifies one of the main reasons that developers love Docker, namely that Docker eliminates "It worked on my machine!?" problems. As currently written, to build a .NET app using this method, a developer onboarding to a project still has read through a long'ish setup readme, familiarize themselves with npm, install it, install .NET framework, etc. And woe betide you if you have the wrong version of any of that software installed, or it's misconfigured. An ops-guy will have the same headaches trying to set up and maintain a CI system.

Note that I'm not opposed to the pattern where you build a slim container for deployment. Here's a PR sent to some of Steve's code showing how this can be combined: https://github.com/SteveLasker/BuildASPDotNetInAContainer/pull/1/files

cc @glennc

kendrahavens · 2017-02-16T22:28:52Z

Thank you @friism. That makes a lot of sense. I'll rework the doc based on your feedback.

friism · 2017-02-17T14:54:18Z

@kendrahavens awesome, let me know if I can help.

It's a little contrived, but here's one way you could do the flow:

docker run -v ${PWD}:/app --workdir /app microsoft/dotnet:1.1.0-sdk-msbuild-rc4 dotnet new mvc
Add Dockerfile similar to this
Show that it builds and runs
Show how to add the .deploy Dockerfile
Do the scripting to copy build output from builder to deploy container as done here.

mdlinville · 2017-03-17T03:08:29Z

Any movement on this? We'd love to get it in!

kendrahavens · 2017-03-27T21:33:14Z

@mstanleyjones Right now we are rewriting this sample to build the app in an sdk container and then run in a runtime container. This way the user avoids needing .NET Core installed on their local machine. We are considering the work on multi-stage builds that looks right for this scenario. So our Dockerfile would look somewhat like:

FROM microsoft/dotnet:1.1-sdk-msbuild
AS build
WORKDIR /app

# copy csproj and restore as distinct layers
COPY dotnetapp.csproj .
RUN dotnet restore

# copy and build everything else
COPY . .
RUN dotnet publish -c Release -o out
ENTRYPOINT ["dotnet", "out/dotnetapp.dll"]

FROM microsoft/dotnet:1.0-runtime
WORKDIR /app
COPY --context=build out .
ENTRYPOINT ["dotnet", "dotnetapp.dll"]

Should I close this and open a new PR when the new sample is ready?

mdlinville · 2017-03-27T23:53:46Z

It is up to you. What is the COPY . . about? I've never seen that syntax before.

kendrahavens · 2017-03-28T18:57:25Z

Cool! COPY is just like Add, but preferred because it is more transparent. It copies files from a source to a destination. The . is the current directory.

friism · 2017-03-28T19:09:26Z

We are considering the work on multi-stage builds that looks right for this scenario

😍

johndmulhausen · 2017-04-14T02:04:18Z

What is the overlap between this and the recently-published https://docs.docker.com/compose/aspnet-mssql-compose/ ?

kendrahavens · 2017-04-14T17:55:19Z

We'd like to have an ASP.NET core example that demonstrates how to build with the onbuild image and deploy with the much-smaller dotnet runtime image. The doc you mentioned covers a compose scenario while there is the simpler "Dockerize an app" scenario that could be a good addition to the Docker engine examples section of the documentation.

glennc · 2017-04-14T18:11:19Z

Multi arch will also change this, along with mutli-stage build.

mdlinville · 2017-05-10T16:55:01Z

Any news?

mdlinville · 2017-06-20T20:52:47Z

Any news?

kendrahavens · 2017-06-21T21:03:45Z

Sorry for not responding sooner! We've been holding off on merging any multi-stage build samples into our samples and guidance repos until it is part of the stable Docker for Windows channel. This shouldn't hold up adding a .NET sample to your docs though! I simply hadn't gotten to it.

mdlinville · 2017-06-22T22:33:31Z

Please remove the stalled label when you are ready for us to review this one again.

mdlinville · 2017-07-07T17:29:13Z

engine/examples/dotnetcore.md

+4.  To make your build context as small as possible add a [`.dockerignore`
+   file](https://docs.docker.com/engine/reference/builder/#dockerignore-file) 
+   to
+   your project folder and copy the following into it.

 ```dockerignore


I don't think this hint works. You can probably go with config.

Hey, I don't understand your meaning here? Could you clarify?

You can't just put anything after the three backticks to give the language "hint". I don't think dockerfile or dockerignore are supported. We aren't using the same highlighter we used to. However, dockerignore wasn't even supported on our old highlighter. You should use conf instead.

thaJeztah

Thanks! Left some suggestions

thaJeztah · 2017-07-09T07:16:02Z

engine/examples/dotnetcore.md

+  (Network Address Translation). You must hit the IP of the container
+  directly. You can get the IP address of your container with the following
+  steps:
+  1.  Run `docker ps` and copy the hash of your container ID.


If you name the container, this step can be simplified, i.e., in the earlier example;

$ docker run -d -p 80:80 --name myapp aspnetapp

thaJeztah · 2017-07-09T07:18:53Z

engine/examples/dotnetcore.md

+2.  Use the following commands to build and run your Docker image:
+
+```console
+docker build -t aspnetapp .


Can you add a prompt ($) here?

```console $ docker build -t aspnetapp . $ docker run -d -p 80:80 aspnetapp ```

thaJeztah · 2017-07-09T07:20:47Z

engine/examples/dotnetcore.md

+
+```console
+docker build -t aspnetapp .
+docker run -d -p 80:80 aspnetapp


it may be worth using a different published port here; port 80 may be taken already on the host, and using a different port for the host than the container can help readers understand "which side" is the container's port and which side the host's port, .e.g. -p 8080:80

thaJeztah · 2017-07-09T07:23:34Z

engine/examples/dotnetcore.md

+  2.  Run `docker inspect -f "{{ .NetworkSettings.Networks.nat.IPAddress }}"
+     HASH` where `HASH` is replaced with your container ID.
+  3.  Copy the container ip address and paste into your browser with port 80.
+     (Ex: 172.16.240.197:80)


We generally use e.g. instead of Ex:; "(e.g., 172.16.240.197:80)"

Also may be worth emphasising the part to copy, either making it bold, or inside back tics

thaJeztah · 2017-07-09T07:26:05Z

engine/examples/dotnetcore.md

+
+This example demonstrates how to dockerize an ASP.NET Core application.
+
+## Why build ASP.NET Core?


Can you add a blank line after all headings? It's consistent with other documents; also, I seem to recall some Markdown renderers having issues if the blank line is missing (but maybe that's no longer the case)

thaJeztah · 2017-07-09T07:26:48Z

engine/examples/dotnetcore.md

+  deployed to the cloud or run on-premise
+- Modular components with minimal overhead retain flexibility while 
+  constructing
+  your solutions


can you re-wrap this line?

thaJeztah · 2017-07-09T07:28:33Z

engine/examples/dotnetcore.md

+## Create a Dockerfile for an ASP.NET Core application
+1.  Create a `Dockerfile` in your project folder.
+2.  Add the text below to your `Dockerfile` for either Linux or [Windows
+   Containers](https://docs.microsoft.com/en-us/virtualization/windowscontainers/about/).


nit: Indenting looks a bit wobbly in this section (but may be GitHub's source code presentation)

I think that's just how it indents when a link is line wrapped. Correct me if I'm wrong. I failed to find guidance for this.

no problem, it was just a nit anyway; perhaps you're right and it's due to it being a link that's wrapped. good call!

mdlinville · 2017-07-11T00:08:54Z

I can't track the place where @thaJeztah told you to use e.g. but I think it is better to say for example, in the text flow, or just leave that off. Popping into Latin that nobody remembers what it stands for can be problematic for people whose first language is not English, and the amount of benefit you get from it is very small.

thaJeztah · 2017-07-11T02:58:03Z

engine/examples/dotnetcore.md

+
+## View the web page running from a container
+
+* Go to [localhost:80](http://localhost:80) to access your app in a web browser.


This should be port 8080 now;

* Go to [localhost:8080](http://localhost:8080) to access your app in a web browser.

Oh shoot, sorry, I double checked in a windows container and forgot about the windows containers not mapping to ports behavior which is why it worked for port 80, but not 8080. I'll leave out the port here.

thaJeztah · 2017-07-11T03:00:00Z

engine/examples/dotnetcore.md

+  steps:
+  1.  Run `docker inspect -f "{{ .NetworkSettings.Networks.nat.IPAddress }}" myapp`
+  2.  Copy the container ip address and paste into your browser with port 80. 
+  (e.g.: `172.16.240.197`:80)


can you include the :80 in the code block?

`172.16.240.197:80`

oh, this is the "e.g." @mstanleyjones was mentioning, so guess it should be

(for example, `172.16.240.197:80`)

kendrahavens · 2017-07-13T18:33:48Z

@mstanleyjones Could you remove the stalled tag? I believe I've addressed all the requested changes.

kendrahavens · 2017-07-18T18:14:26Z

@mstanleyjones @thaJeztah Hey folks, are there any more changes I can make? I see the deploy/netlify preview failed. Is there anything I can fix to get it passing?

mdlinville · 2017-07-24T17:04:20Z

I removed the stalled label. You can make Netlify start again by amending and force-pushing the commit. Let me checkout this PR and verify that it builds locally, though.

mdlinville · 2017-07-24T17:10:35Z

FYI there are some mistakes in the YAML of the file. You can't word-wrap in the YAML without changing the syntax of it. I'll push a commit that fixes that after I finish testing locally.

mdlinville · 2017-07-24T17:49:14Z

I found a few more problems, still working on this. I'll push all the commits I've added when I get this into a better state.

kendrahavens · 2017-07-25T18:31:32Z

@mstanleyjones Thank you so much for your help on this!

mdlinville · 2017-07-25T18:34:46Z

@johndmulhausen I tested this locally and it works fine. Netlify is busted thinking it's against the vnext-engine branch. Can you please squash and merge this, and make sure to clean up the commit message when squashing? Thanks!

johndmulhausen · 2017-07-25T18:41:26Z

Thanks for the review @mstanleyjones !

Add Dockerize and ASP.NET Core doc

mdlinville suggested changes Feb 15, 2017

View reviewed changes

mdlinville requested review from johndmulhausen and friism February 15, 2017 21:15

johndmulhausen requested review from JimGalasyn and removed request for friism April 8, 2017 00:51

mdlinville added the stalled label Jun 22, 2017

mdlinville reviewed Jul 7, 2017

View reviewed changes

thaJeztah requested changes Jul 9, 2017

View reviewed changes

thaJeztah requested changes Jul 11, 2017

View reviewed changes

kendrahavens and others added 4 commits July 13, 2017 12:13

Add Dockerize and ASP.NET Core doc

7510291

Add additional spacing to clean up deploy preview

04c83c0

Add multi-stage build

6e5bc1a

addressing thaJeztah's feedback

726bb33

Fixed port mapping

01d25ec

mdlinville removed the stalled label Jul 24, 2017

Fix YAML

8127e64

Misty Stanley-Jones added 2 commits July 24, 2017 10:13

Add raw tags to double-bracketed expression

4968e08

Remove gerund, add to TOC

2e8dcc4

johndmulhausen merged commit c171853 into docker:master Jul 25, 2017

shin- pushed a commit to shin-/docker.github.io that referenced this pull request Aug 19, 2017

Add Dockerize and ASP.NET Core doc (docker#1681)

c91737e

Add Dockerize and ASP.NET Core doc

friism mentioned this pull request Sep 6, 2017

Build Docker Windows Container-related content #225

Closed


		This example demonstrates how to dockerize an ASP.NET Core application.

		> Note: This example assumes you already have a published ASP.NET Core app on your machine. If you are new to ASP.NET you can follow a [simple tutorial](https://www.asp.net/get-started) to initialize a project.


		This example demonstrates how to dockerize an ASP.NET Core application.

		## Why build ASP.NET Core?


		## View the web page running from a container

		* Go to [localhost:80](http://localhost:80) to access your app in a web browser.

Add Dockerize and ASP.NET Core doc #1681

Add Dockerize and ASP.NET Core doc #1681

Conversation

kendrahavens commented Feb 15, 2017 • edited Loading

Proposed changes

mdlinville left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

friism commented Feb 15, 2017

kendrahavens commented Feb 16, 2017

friism commented Feb 17, 2017

mdlinville commented Mar 17, 2017

kendrahavens commented Mar 27, 2017

mdlinville commented Mar 27, 2017

kendrahavens commented Mar 28, 2017

friism commented Mar 28, 2017

johndmulhausen commented Apr 14, 2017

kendrahavens commented Apr 14, 2017

glennc commented Apr 14, 2017

mdlinville commented May 10, 2017

mdlinville commented Jun 20, 2017

kendrahavens commented Jun 21, 2017

mdlinville commented Jun 22, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thaJeztah left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mdlinville commented Jul 11, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kendrahavens commented Jul 13, 2017

kendrahavens commented Jul 18, 2017

mdlinville commented Jul 24, 2017

mdlinville commented Jul 24, 2017

mdlinville commented Jul 24, 2017

kendrahavens commented Jul 25, 2017

mdlinville commented Jul 25, 2017

johndmulhausen commented Jul 25, 2017

kendrahavens commented Feb 15, 2017 •

edited

Loading