Lets get started.<\/p>\n
Prerequisites<\/h2>\n\n- Golang<\/a> [Local Workstation]<\/li>\n
- Docker<\/a> [Local Workstation]<\/li>\n<\/ol>\n
Once you ensure all the requirements are available, we can start building the application.<\/p>\n
Steps to Dockerize a Golang Application<\/h2>\n
Follow the steps to Dockerize a Golang application.<\/p>\n
Step 1: Clone the Repo<\/h2>\n
I have stored this tutorial’s contents on the public repository, you can clone and use it if required.<\/p>\n
git clone https:\/\/github.com\/techiescamp-docker-images\/dockerize-go-web-app.git<\/code><\/pre>\nThe following is the structure of the cloned repository.<\/p>\n
cd dockerize-go-web-app\/hello-world<\/code><\/pre>\n.\n\u251c\u2500\u2500 Dockerfile\n\u251c\u2500\u2500 go.mod\n\u251c\u2500\u2500 index.html\n\u2514\u2500\u2500 main.go<\/code><\/pre>\nNow, we can start creating a simple Golang application.<\/p>\n
Step 2: Create a Golang Application<\/h2>\n\nNote:<\/strong><\/b> If you have an existing Golang application, skip this step and move to the step 5 to Dockerize it directly.<\/div>\n<\/div>\nFirst, you need to create a directory named go-web-app<\/code> and initialize the Go module.<\/p>\ngo mod init go-app<\/code><\/pre>\nThis will create a module file and create a main file named main.go<\/code> for our application.<\/p>\nAdd the following contents to the file.<\/p>\n
package main\n\nimport (\n \"io\/ioutil\"\n \"log\"\n \"net\/http\"\n)\n\nfunc handler(w http.ResponseWriter, r *http.Request) {\n \/\/ Read the HTML file\n html, err := ioutil.ReadFile(\"index.html\")\n if err != nil {\n http.Error(w, \"Could not read HTML file\", http.StatusInternalServerError)\n return\n }\n\n \/\/ Set the content type to HTML and write the HTML content\n w.Header().Set(\"Content-Type\", \"text\/html\")\n w.Write(html)\n}\n\nfunc main() {\n http.HandleFunc(\"\/\", handler)\n log.Println(\"Server is listening on port 8080\")\n if err := http.ListenAndServe(\":8080\", nil); err != nil {\n log.Fatalf(\"Failed to start server: %s\", err)\n }\n}<\/code><\/pre>\nTo create this application, I have used these three packages.<\/p>\n
\n- io\/ioutil <\/strong>– This package is used to read\/write files. I am using a custom HTML page for the output.<\/li>\n
- log <\/strong>– This package is used to generate logs based on the errors and status.<\/li>\n
- net\/http<\/strong> – This is the major package that handles the HTTP<\/strong> requests and responses of our web application.<\/li>\n<\/ul>\n
Step 3: Create the HTML File<\/h2>\n
Create an HTML file (index.html<\/code>) for our web application and add the following contents.<\/p>\n<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n <meta charset=\"UTF-8\">\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n <title>Hello, World!<\/title>\n <link href=\"https:\/\/fonts.googleapis.com\/css2?family=Roboto:wght@300&display=swap\" rel=\"stylesheet\">\n <style>\n body {\n display: flex;\n justify-content: center;\n align-items: center;\n height: 100vh;\n margin: 0;\n background: linear-gradient(135deg, #f5f7fa, #c3cfe2);\n font-family: 'Roboto', sans-serif;\n }\n .hello {\n font-size: 3em;\n text-align: center;\n color: #333;\n padding: 20px;\n border-radius: 10px;\n background: rgba(255, 255, 255, 0.8);\n box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);\n }\n <\/style>\n<\/head>\n<body>\n <div class=\"hello\">\n <p>Hello, World!<\/p>\n <\/div>\n<\/body>\n<\/html><\/code><\/pre>\nOnce the main Go file and HTML file are ready, we can test them from our local machine<\/p>\n
Step 4: Run the Application Locally<\/h2>\n
Before we run the application, we need to compile the code.<\/p>\n
To compile and run the application, use the following command.<\/p>\n
go run main.go<\/code><\/pre>\nOnce the app starts running, we can access the web page from our local machine.<\/p>\n
For that, open any browser and paste the URL http:\/\/localhost:8080\/<\/code><\/p>\n![\"the](\"https:\/\/storage.ghost.io\/c\/5f\/2f\/5f2f4d20-2abf-4534-8d40-7aa233aedd43\/content\/images\/2025\/08\/image-40.png\")
<\/figure>\nNow, we confirmed that our application is running without any issues, so we can start containerizing the application.<\/p>\n
Step 5: Create a Dockerfile for the Go Application<\/h2>\n
We need to build a Docker image<\/a> using a multi-stage<\/strong> build to optimize the Docker image.<\/a><\/p>\nWe will look at both scratch image and distroless image options.<\/p>\n
Golang image using scratch image<\/h3>\n\n\ud83d\udca1<\/div>\nA scratch image<\/strong><\/b> in Docker is basically an empty base image<\/strong><\/b>. It is the starting point when you dont want to use any existing operating system image like alpine<\/code> or ubuntu<\/code>. Instead, you build your image from nothing<\/strong><\/b>, only adding the files you need.<\/p>\nIt works well with Golang because, Go programs can be compiled into a self-contained static binary<\/strong><\/b> that doesn\u2019t need any operating system packages.<\/div>\n<\/div>\nCreate a Dockerfile<\/code> and add the following contents.<\/p>\n# Stage 1: Build the Go binary\nFROM golang:1.21-alpine AS builder\n\nRUN adduser -D builderuser\n\nWORKDIR \/app\n\n\nCOPY main.go .\nCOPY index.html .\n\n# Use go modules if needed \n# COPY go.mod go.sum .\/\n# RUN go mod download\n\n\nRUN CGO_ENABLED=0 GOOS=linux go build -o server main.go\n\n# Stage 2: Minimal secure runtime\nFROM scratch\n\nWORKDIR \/app\n\nCOPY --from=builder \/app\/server .\nCOPY --from=builder \/app\/index.html .\n\nUSER 1000\n\nEXPOSE 8080\n\nENTRYPOINT [\".\/server\"]<\/code><\/pre>\nNow, we have created the Dockerfile<\/code>.<\/p>\nThe following is the explanation of what we have done in the Dockerfile<\/code> to optimize the build.<\/p>\n\n- In stage 1, we use the official
golang:1.21-alpine<\/code> image to download the dependencies and compile the code.<\/li>\n- Then we compile go app with
CGO_ENABLED=0 GOOS=linux go build<\/code> that produces a single binary file that contains your code, Go runtime and all the dependencies.<\/li>\n- In stage 2, we have used a lightweight Scratch image<\/strong> to run the compiled code from stage 1.<\/li>\n
- To follow the security best practices, we created a non-root user
builduser,<\/code> to run the application inside the container.<\/li>\n- Exposing the application on Port
8080<\/code> to access the application.<\/li>\n<\/ol>\nAlthough scratch image are very minimal, it comes with certain disadvantages. For example, it does not include the standard CA certificate bundle (\/etc\/ssl\/certs\/ca-certificates.crt). <\/p>\n
Many apps (APIs, web servers, DB clients) need TLS\/SSL certificates<\/strong> (like root CAs) to make secure HTTPS connections.<\/p>\nThat means you must manually copy certificates<\/strong> into the image and keep them updated.<\/p>\nSo a better and safe alternative is Distroless images explained in the next section.<\/p>\n
Golang Image using Distroless Base Image<\/h3>\n
For enterprise environments, the certificate management complexity alone often makes distroless more practical than true scratch images.<\/p>\n
Here is the Dockerfile using Distroless base image<\/a>.<\/p>\n# Stage 1: Build the Go binary\nFROM golang:1.21-alpine AS builder\nWORKDIR \/app\n\nCOPY main.go .\nCOPY index.html .\n\nRUN CGO_ENABLED=0 GOOS=linux go build -ldflags=\"-s -w\" -o server main.go\n\n# Stage 2: Distroless runtime with basic OS data\nFROM gcr.io\/distroless\/base\nWORKDIR \/app\n\nCOPY --from=builder \/app\/server \/app\/server\nCOPY --from=builder \/app\/index.html \/app\/index.html\n\nUSER nonroot:nonroot\n\nEXPOSE 8080\nENTRYPOINT [\"\/app\/server\"]<\/code><\/pre>\nStep 6: Create a Container Image<\/h2>\n
To create the container image, use the following command with any of the Dockerfiles from above.<\/p>\n
sudo docker build -t go-web-app .<\/code><\/pre>\ngo-web-app<\/code> is the image name, you can change it if required.<\/p>\nTo list the available images, use the following command.<\/p>\n
$ sudo docker images\n\nREPOSITORY TAG IMAGE ID CREATED SIZE\ngo-web-app latest fbfe728d2742 2 minutes ago 6.72MB\n<\/code><\/pre>\nOnce the container image is created, it is better to push it to a repository like Docker Hub or JFrog.<\/p>\n
Now, the container image is ready, so we can run the container.<\/p>\n
Step 7: Run Containerized Go Application<\/h2>\n
The Go web application container image is ready, so we can create a container with this image.<\/p>\n
sudo docker run -d --name go-app -p 8080:8080 go-web-app<\/code><\/pre>\n\ngo-app<\/code> – Name of the container<\/li>\n-p 8080:8080<\/code> – Map host port 8080 to the container port 8080<\/li>\ngo-web-app<\/code> – Name of the container image that we built.<\/li>\n<\/ul>\nTo list the running containers, use the following command.<\/p>\n
$ sudo docker ps\n\nCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES\n7f4d904b3f84 go-web-app \".\/server\" 6 minutes ago Up 6 minutes 0.0.0.0:8080->8080\/tcp go-app<\/code><\/pre>\nNow, we can try to access our application using the URL.<\/p>\n<\/figure>\nHere, we have used localhost<\/code> because the application is running on our local Docker engine, but if you are using a cloud instance like EC2, then you can use the IP address of the instance instead of localhost.<\/p>\nNow, our deployment is completed, though we need to follow the security practices if we are doing this for an organization or in a real project.<\/p>\n
Container Security Best Practices<\/h2>\n
Vulnerabilities can be present in both the Dockerfile<\/a> and the container images, so we need to scan them both. <\/p>\nScan the Dockerfile<\/h3>\n
To scan the Dockerfile<\/strong> and identify the misconfiguration, we are using a linting tool, which is Hadolint.<\/strong><\/p>\nTo install the Hadolint on your machine and learn more about it, refer to this blog.<\/a><\/p>\nCurrently, our Dockerfile doesn’t have any issues, though I have made some intentional misconfiguration for the demo<\/p>\n
hadolint Dockerfile<\/code><\/pre>\nThe output will prompt where the changes are required, and if your Dockerfile doesn’t have any issues, you will not see any output.<\/p>\n![\"hadolint](\"https:\/\/storage.ghost.io\/c\/5f\/2f\/5f2f4d20-2abf-4534-8d40-7aa233aedd43\/content\/images\/2025\/03\/image-71.png\")
<\/figure>\nNow, we can scan the container image.<\/p>\n
Scan Container Image<\/h3>\n
To identify the vulnerabilities of our container, we can use the Trivy<\/strong> tool.<\/p>\nTo install Trivy<\/a> and to know about its use cases, you can refer to this blog.<\/a><\/p>\nAfter installing the utility, use the following command to identify the vulnerabilities of the container image.<\/p>\n
sudo trivy image go-web-app<\/code><\/pre>\nThis will list the vulnerabilities based on the severity levels.<\/p>\n![\"trivy](\"https:\/\/storage.ghost.io\/c\/5f\/2f\/5f2f4d20-2abf-4534-8d40-7aa233aedd43\/content\/images\/2025\/03\/image-72.png\")
<\/figure>\nThis is how we containerize a Go application.<\/p>\n
Conclusion<\/h2>\n
We have successfully containerized our Go web application. This helps you understand how to containerize your own Golang applications.<\/p>\n
There is more you can do with that, and don’t forget to store the container image in a container repo such as Dockerhub or ECR.<\/p>\n
Always follow the security best practices when you containerize the application, and you can also integrate these scanning tools into your CI\/CD pipelines<\/a> to automate the process.<\/p>\n
\n
Once you ensure all the requirements are available, we can start building the application.<\/p>\n
Steps to Dockerize a Golang Application<\/h2>\n
Follow the steps to Dockerize a Golang application.<\/p>\n
Step 1: Clone the Repo<\/h2>\n
I have stored this tutorial’s contents on the public repository, you can clone and use it if required.<\/p>\n
git clone https:\/\/github.com\/techiescamp-docker-images\/dockerize-go-web-app.git<\/code><\/pre>\nThe following is the structure of the cloned repository.<\/p>\n
cd dockerize-go-web-app\/hello-world<\/code><\/pre>\n.\n\u251c\u2500\u2500 Dockerfile\n\u251c\u2500\u2500 go.mod\n\u251c\u2500\u2500 index.html\n\u2514\u2500\u2500 main.go<\/code><\/pre>\nNow, we can start creating a simple Golang application.<\/p>\n
Step 2: Create a Golang Application<\/h2>\n\nNote:<\/strong><\/b> If you have an existing Golang application, skip this step and move to the step 5 to Dockerize it directly.<\/div>\n<\/div>\nFirst, you need to create a directory named go-web-app<\/code> and initialize the Go module.<\/p>\ngo mod init go-app<\/code><\/pre>\nThis will create a module file and create a main file named main.go<\/code> for our application.<\/p>\nAdd the following contents to the file.<\/p>\n
package main\n\nimport (\n \"io\/ioutil\"\n \"log\"\n \"net\/http\"\n)\n\nfunc handler(w http.ResponseWriter, r *http.Request) {\n \/\/ Read the HTML file\n html, err := ioutil.ReadFile(\"index.html\")\n if err != nil {\n http.Error(w, \"Could not read HTML file\", http.StatusInternalServerError)\n return\n }\n\n \/\/ Set the content type to HTML and write the HTML content\n w.Header().Set(\"Content-Type\", \"text\/html\")\n w.Write(html)\n}\n\nfunc main() {\n http.HandleFunc(\"\/\", handler)\n log.Println(\"Server is listening on port 8080\")\n if err := http.ListenAndServe(\":8080\", nil); err != nil {\n log.Fatalf(\"Failed to start server: %s\", err)\n }\n}<\/code><\/pre>\nTo create this application, I have used these three packages.<\/p>\n
\n- io\/ioutil <\/strong>– This package is used to read\/write files. I am using a custom HTML page for the output.<\/li>\n
- log <\/strong>– This package is used to generate logs based on the errors and status.<\/li>\n
- net\/http<\/strong> – This is the major package that handles the HTTP<\/strong> requests and responses of our web application.<\/li>\n<\/ul>\n
Step 3: Create the HTML File<\/h2>\n
Create an HTML file (index.html<\/code>) for our web application and add the following contents.<\/p>\n<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n <meta charset=\"UTF-8\">\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n <title>Hello, World!<\/title>\n <link href=\"https:\/\/fonts.googleapis.com\/css2?family=Roboto:wght@300&display=swap\" rel=\"stylesheet\">\n <style>\n body {\n display: flex;\n justify-content: center;\n align-items: center;\n height: 100vh;\n margin: 0;\n background: linear-gradient(135deg, #f5f7fa, #c3cfe2);\n font-family: 'Roboto', sans-serif;\n }\n .hello {\n font-size: 3em;\n text-align: center;\n color: #333;\n padding: 20px;\n border-radius: 10px;\n background: rgba(255, 255, 255, 0.8);\n box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);\n }\n <\/style>\n<\/head>\n<body>\n <div class=\"hello\">\n <p>Hello, World!<\/p>\n <\/div>\n<\/body>\n<\/html><\/code><\/pre>\nOnce the main Go file and HTML file are ready, we can test them from our local machine<\/p>\n
Step 4: Run the Application Locally<\/h2>\n
Before we run the application, we need to compile the code.<\/p>\n
To compile and run the application, use the following command.<\/p>\n
go run main.go<\/code><\/pre>\nOnce the app starts running, we can access the web page from our local machine.<\/p>\n
For that, open any browser and paste the URL http:\/\/localhost:8080\/<\/code><\/p>\n<\/figure>\nNow, we confirmed that our application is running without any issues, so we can start containerizing the application.<\/p>\n
Step 5: Create a Dockerfile for the Go Application<\/h2>\n
We need to build a Docker image<\/a> using a multi-stage<\/strong> build to optimize the Docker image.<\/a><\/p>\nWe will look at both scratch image and distroless image options.<\/p>\n
Golang image using scratch image<\/h3>\n\n\ud83d\udca1<\/div>\nA scratch image<\/strong><\/b> in Docker is basically an empty base image<\/strong><\/b>. It is the starting point when you dont want to use any existing operating system image like alpine<\/code> or ubuntu<\/code>. Instead, you build your image from nothing<\/strong><\/b>, only adding the files you need.<\/p>\nIt works well with Golang because, Go programs can be compiled into a self-contained static binary<\/strong><\/b> that doesn\u2019t need any operating system packages.<\/div>\n<\/div>\nCreate a Dockerfile<\/code> and add the following contents.<\/p>\n# Stage 1: Build the Go binary\nFROM golang:1.21-alpine AS builder\n\nRUN adduser -D builderuser\n\nWORKDIR \/app\n\n\nCOPY main.go .\nCOPY index.html .\n\n# Use go modules if needed \n# COPY go.mod go.sum .\/\n# RUN go mod download\n\n\nRUN CGO_ENABLED=0 GOOS=linux go build -o server main.go\n\n# Stage 2: Minimal secure runtime\nFROM scratch\n\nWORKDIR \/app\n\nCOPY --from=builder \/app\/server .\nCOPY --from=builder \/app\/index.html .\n\nUSER 1000\n\nEXPOSE 8080\n\nENTRYPOINT [\".\/server\"]<\/code><\/pre>\nNow, we have created the Dockerfile<\/code>.<\/p>\nThe following is the explanation of what we have done in the Dockerfile<\/code> to optimize the build.<\/p>\n\n- In stage 1, we use the official
golang:1.21-alpine<\/code> image to download the dependencies and compile the code.<\/li>\n- Then we compile go app with
CGO_ENABLED=0 GOOS=linux go build<\/code> that produces a single binary file that contains your code, Go runtime and all the dependencies.<\/li>\n- In stage 2, we have used a lightweight Scratch image<\/strong> to run the compiled code from stage 1.<\/li>\n
- To follow the security best practices, we created a non-root user
builduser,<\/code> to run the application inside the container.<\/li>\n- Exposing the application on Port
8080<\/code> to access the application.<\/li>\n<\/ol>\nAlthough scratch image are very minimal, it comes with certain disadvantages. For example, it does not include the standard CA certificate bundle (\/etc\/ssl\/certs\/ca-certificates.crt). <\/p>\n
Many apps (APIs, web servers, DB clients) need TLS\/SSL certificates<\/strong> (like root CAs) to make secure HTTPS connections.<\/p>\nThat means you must manually copy certificates<\/strong> into the image and keep them updated.<\/p>\nSo a better and safe alternative is Distroless images explained in the next section.<\/p>\n
Golang Image using Distroless Base Image<\/h3>\n
For enterprise environments, the certificate management complexity alone often makes distroless more practical than true scratch images.<\/p>\n
Here is the Dockerfile using Distroless base image<\/a>.<\/p>\n# Stage 1: Build the Go binary\nFROM golang:1.21-alpine AS builder\nWORKDIR \/app\n\nCOPY main.go .\nCOPY index.html .\n\nRUN CGO_ENABLED=0 GOOS=linux go build -ldflags=\"-s -w\" -o server main.go\n\n# Stage 2: Distroless runtime with basic OS data\nFROM gcr.io\/distroless\/base\nWORKDIR \/app\n\nCOPY --from=builder \/app\/server \/app\/server\nCOPY --from=builder \/app\/index.html \/app\/index.html\n\nUSER nonroot:nonroot\n\nEXPOSE 8080\nENTRYPOINT [\"\/app\/server\"]<\/code><\/pre>\nStep 6: Create a Container Image<\/h2>\n
To create the container image, use the following command with any of the Dockerfiles from above.<\/p>\n
sudo docker build -t go-web-app .<\/code><\/pre>\ngo-web-app<\/code> is the image name, you can change it if required.<\/p>\nTo list the available images, use the following command.<\/p>\n
$ sudo docker images\n\nREPOSITORY TAG IMAGE ID CREATED SIZE\ngo-web-app latest fbfe728d2742 2 minutes ago 6.72MB\n<\/code><\/pre>\nOnce the container image is created, it is better to push it to a repository like Docker Hub or JFrog.<\/p>\n
Now, the container image is ready, so we can run the container.<\/p>\n
Step 7: Run Containerized Go Application<\/h2>\n
The Go web application container image is ready, so we can create a container with this image.<\/p>\n
sudo docker run -d --name go-app -p 8080:8080 go-web-app<\/code><\/pre>\n\ngo-app<\/code> – Name of the container<\/li>\n-p 8080:8080<\/code> – Map host port 8080 to the container port 8080<\/li>\ngo-web-app<\/code> – Name of the container image that we built.<\/li>\n<\/ul>\nTo list the running containers, use the following command.<\/p>\n
$ sudo docker ps\n\nCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES\n7f4d904b3f84 go-web-app \".\/server\" 6 minutes ago Up 6 minutes 0.0.0.0:8080->8080\/tcp go-app<\/code><\/pre>\nNow, we can try to access our application using the URL.<\/p>\n<\/figure>\nHere, we have used localhost<\/code> because the application is running on our local Docker engine, but if you are using a cloud instance like EC2, then you can use the IP address of the instance instead of localhost.<\/p>\nNow, our deployment is completed, though we need to follow the security practices if we are doing this for an organization or in a real project.<\/p>\n
Container Security Best Practices<\/h2>\n
Vulnerabilities can be present in both the Dockerfile<\/a> and the container images, so we need to scan them both. <\/p>\nScan the Dockerfile<\/h3>\n
To scan the Dockerfile<\/strong> and identify the misconfiguration, we are using a linting tool, which is Hadolint.<\/strong><\/p>\nTo install the Hadolint on your machine and learn more about it, refer to this blog.<\/a><\/p>\nCurrently, our Dockerfile doesn’t have any issues, though I have made some intentional misconfiguration for the demo<\/p>\n
hadolint Dockerfile<\/code><\/pre>\nThe output will prompt where the changes are required, and if your Dockerfile doesn’t have any issues, you will not see any output.<\/p>\n<\/figure>\nNow, we can scan the container image.<\/p>\n
Scan Container Image<\/h3>\n
To identify the vulnerabilities of our container, we can use the Trivy<\/strong> tool.<\/p>\nTo install Trivy<\/a> and to know about its use cases, you can refer to this blog.<\/a><\/p>\nAfter installing the utility, use the following command to identify the vulnerabilities of the container image.<\/p>\n
sudo trivy image go-web-app<\/code><\/pre>\nThis will list the vulnerabilities based on the severity levels.<\/p>\n<\/figure>\nThis is how we containerize a Go application.<\/p>\n
Conclusion<\/h2>\n
We have successfully containerized our Go web application. This helps you understand how to containerize your own Golang applications.<\/p>\n
There is more you can do with that, and don’t forget to store the container image in a container repo such as Dockerhub or ECR.<\/p>\n
Always follow the security best practices when you containerize the application, and you can also integrate these scanning tools into your CI\/CD pipelines<\/a> to automate the process.<\/p>\n
\n