NGINX is one of the most popular web servers in the world. Not only is NGINX a fast and reliable static web server, it is also used by a ton of developers as a reverse-proxy that sits in front of their APIs.
Integrate image storage and distribution tightly into your in-house development workflow Alternatives Users looking for a zero maintenance, ready-to-go solution are encouraged to head-over to the Docker Hub, which provides a free-to-use, hosted Registry, plus additional features (organization accounts, automated builds, and more). Then you can smoothly upgrade to latest docker version $ sudo apt-get update # remove the old $ sudo apt-get purge lxc-docker. # install the new $ sudo apt-get install docker-engine And in the case that you don't want to install latest package then you can do something like below. $ sudo apt-get install docker-engine=1.7.1-0trusty for docker-ce.
In this tutorial we will take a look at the NGINX Official Docker Image and how to use it. We’ll start by running a static web server locally then we’ll build a custom image to house our web server and the files it needs to serve. We’ll finish up by taking a look at creating a reverse-proxy server for a simple REST API and then how to share this image with your team.
Docker Upgrade Image
Prerequisites
Docker Upgrade Image Windows 10
To complete this tutorial, you will need the following:
- Free Docker Account
- You can sign-up for a free Docker account and receive free unlimited public repositories
- Docker running locally
- An IDE or text editor to use for editing files. I would recommend VSCode
NGINX Official Image
The Docker Official Images are a curated set of Docker repositories hosted on Docker Hub that have been scanned for vulnerabilities and are maintained by Docker employees and upstream maintainers.
Official Images are a great place for new Docker users to start. These images have clear documentation, promote best practices, and are designed for the most common use cases.
Let’s take a look at the NGINX official image. Open your favorite browser and log into Docker. If you do not have a Docker account yet, you can create one for free.
Once you have logged into Docker, enter “NGINX” into the top search bar and press enter. The official NGINX image should be the first image in the search results. You will see the “OFFICIAL IMAGE” label in the top right corner of the search entry.
Now click on the nginx result to view the image details.
On the image details screen, you are able to view the description of the image and it’s readme. You can also see all the tags that are available by clicking on the “Tags” tab
Running a basic web server
Let’s run a basic web server using the official NGINX image. Run the following command to start the container.
With the above command, you started running the container as a daemon (-d) and published port 8080 on the host network. You also named the container web using the --name option.
Open your favorite browser and navigate to http://localhost:8080 You should see the following NGINX welcome page.
This is great but the purpose of running a web server is to serve our own custom html files and not the default NGINX welcome page.
Let’s stop the container and take a look at serving our own HTML files.
Adding Custom HTML
By default, Nginx looks in the /usr/share/nginx/html directory inside of the container for files to serve. We need to get our html files into this directory. A fairly simple way to do this is use a mounted volume. With mounted volumes, we are able to link a directory on our local machine and map that directory into our running container.
Let’s create a custom html page and then serve that using the nginx image.
Create a directory named site-content. In this directory add an index.html file and add the following html to it:
Now run the following command, which is the same command as above, but now we’ve added the -v flag to create a bind mount volume. This will mount our local directory ~/site-content locally into the running container at: /usr/share/nginx/html
Open your favorite browser and navigate to http://localhost:8080 and you should see the above html rendered in your browser window.
Build Custom NGINX Image
Bind mounts are a great option for running locally and sharing files into a running container. But what if we want to move this image around and have our html files moved with it?
There are a couple of options available but one of the most portable and simplest ways to do this is to copy our html files into the image by building a custom image.
To build a custom image, we’ll need to create a Dockerfile and add our commands to it.
In the same directory, create a file named Dockerfile and paste the below commands.
We start building our custom image by using a base image. On line 1, you can see we do this using the FROM command. This will pull the nginx:latest image to our local machine and then build our custom image on top of it.
Next, we COPY our index.html file into the /usr/share/nginx/html directory inside the container overwriting the default index.html file provided by nginx:latest image.
You’ll notice that we did not add an ENTRYPOINT or a CMD to our Dockerfile. We will use the underlying ENTRYPOINT and CMD provided by the base NGINX image.
To build our image, run the following command:
The build command will tell Docker to execute the commands located in our Dockerfile. You will see a similar output in your terminal as below:
Now we can run our image in a container but this time we do not have to create a bind mount to include our html.
Open your browser and navigate to http://localhost:8080 to make sure our html page is being served correctly.
Setting up a reverse proxy server
A very common scenario for developers, is to run their REST APIs behind a reverse proxy. There are many reasons why you would want to do this but one of the main reasons is to run your API server on a different network or IP then your front-end application is on. You can then secure this network and only allow traffic from the reverse proxy server.
For the sake of simplicity and space, I’ve created a simple frontend application in React.js and a simple backend API written in Node.js. Run the following command to pull the code from GitHub.
Once you’ve cloned the repo, open the project in your favorite IDE. Take a look at Dockerfile in the frontend directory.
The Dockerfile sets up a multi-stage build. We first build our React.js application and then we copy the nginx.conf file from our local machine into the image along with our static html and javascript files that were built in the first phase.
We configure the reverse proxy in the frontend/nginx/nginx.conf file. You can learn more about configuring Nginx in their documentation.
As you can see in the second location section thatall traffic targeted to /services/m will be proxy_pass to http://backend:8080/services/m
In the root of the project is a Docker Compose file that will start both our frontend and backend services. Let’s start up our application and test if the reverse proxy is working correctly.
You can see that our nginx web server has started and also our backend_1 service has started and is listening on port 8080.
Open your browser and navigate to http://localhost. You should see the following web page:
Open the developer tools window and click on the “network” tab. Now back in the browser, enter an entity name. This can be anything. I’m going to use “widgets”. Then click the “Submit” button.
Over in the developer tools window, click on the network request for widgets and see that the request was made to http://localhost and not to http://localhost:8080.
Open your terminal and notice that request that was made from the browser was proxied to the backend_1 service and handled correctly.
Shipping Our Image
Now let’s share our images on Docker so others on our team can pull the images and run them locally. This is also a great way to share your application with others outside of your team such as testers and business owners.
To push your images to Docker’s repository run the docker tag and then the docker push commands. You will first need to login with your Docker ID. If you do not have a free account, you can create one here.
Awesome Compose
The Awesome compose project is a curated list of Docker Compose samples. These samples provide a starting point for how to integrate different services using a Compose file and to manage their deployment with Docker Compose.
In the awesome compose repository you can find project templates that use NGINX as a static web server or a reverse proxy. Please take a look and if you do not find what you are looking for please consider contributing to the project. Checkout the Contribution Guide for more details.
Conclusion
In this article we walked through running the NGINX official image, adding our custom html files, building a custom image based off of the official image and configuring the NGINX as a reverse proxy. We finished up by pushing our custom image to Docker so we could share with others on our team.
If you have any questions, please feel free to reach out on Twitter @pmckee and join us in our community slack.
Estimated reading time: 7 minutes
Docker Hub repositories allow you share container images with your team,customers, or the Docker community at large.
Docker images are pushed to Docker Hub through the docker pushcommand. A single Docker Hub repository can hold many Docker images (stored astags).
Creating repositories
To create a repository, sign into Docker Hub, click on Repositories thenCreate Repository:
When creating a new repository:
- You can choose to put it in your Docker ID namespace, or in anyorganization where you are an owner.
- The repository name needs to be unique in that namespace, can be twoto 255 characters, and can only contain lowercase letters, numbers, hyphens (
-),and underscores (_). - The description can be up to 100 characters and is used in the search result.
- You can link a GitHub or Bitbucket account now, or choose to do it later inthe repository settings.
After you hit the Create button, you can start using docker push to pushimages to this repository.
Pushing a Docker container image to Docker Hub
To push an image to Docker Hub, you must first name your local image using yourDocker Hub username and the repository name that you created through Docker Hubon the web.
You can add multiple images to a repository by adding a specific :<tag> tothem (for example docs/base:testing). If it’s not specified, the tag defaultsto latest.
Name your local images using one of these methods:
- When you build them, using
docker build -t <hub-user>/<repo-name>[:<tag>] - By re-tagging an existing local image
docker tag <existing-image> <hub-user>/<repo-name>[:<tag>] - By using
docker commit <existing-container> <hub-user>/<repo-name>[:<tag>]to commit changes
Docker Upgrade Image App
Now you can push this repository to the registry designated by its name or tag.
The image is then uploaded and available for use by your teammates and/orthe community.
Private repositories
Private repositories let you keep container images private, either to yourown account or within an organization or team.
To create a private repository, select Private when creating a repository:
You can also make an existing repository private by going to its Settings tab:
You get one private repository for free with your Docker Hub user account (notusable for organizations you’re a member of). If you need more privaterepositories for your user account, upgrade your Docker Hub plan from yourBilling Information page.
Once the private repository is created, you can push and pull images to andfrom it using Docker.
Note: You need to be signed in and have access to work with aprivate repository.
Note: Private repositories are not currently available to search throughthe top-level search or docker search.
You can designate collaborators and manage their access to a privaterepository from that repository’s Settings page. You can also toggle therepository’s status between public and private, if you have an availablerepository slot open. Otherwise, you can upgrade yourDocker Hub plan.
Collaborators and their role
A collaborator is someone you want to give access to a private repository. Oncedesignated, they can push and pull to your repositories. They are notallowed to perform any administrative tasks such as deleting the repository orchanging its status from private to public.
Note
A collaborator cannot add other collaborators. Only the owner ofthe repository has administrative access.
You can also assign more granular collaborator rights (“Read”, “Write”, or“Admin”) on Docker Hub by using organizations and teams. For more informationsee the organizations documentation.
Viewing repository tags
Docker Hub’s individual repositories view shows you the available tags and thesize of the associated image. Go to the Repositories view and click on arepository to see its tags.
Image sizes are the cumulative space taken up by the image and all its parentimages. This is also the disk space used by the contents of the .tar filecreated when you docker save an image.
To view individual tags, click on the Tags tab.
An image is considered stale if there has been no push/pull activity for morethan 1 month, i.e.:
- It has not been pulled for more than 1 month
- And it has not been pushed for more than 1 month
A multi-architecture image is considered stale if all single-architecture imagespart of its manifest are stale.
To delete a tag, select the corresponding checkbox and select Delete from theAction drop-down list.
Note
Only a user with administrative access (owner or team member with Adminpermission) over the repository can delete tags.
Select a tag’s digest to view details.
Searching for Repositories
You can search the Docker Hub registry through itssearch interface or by using the command line interface. Searching can findimages by image name, username, or description:
There you can see two example results: centos and ansible/centos7-ansible.The second result shows that it comes from the public repository of a user,named ansible/, while the first result, centos, doesn’t explicitly list arepository which means that it comes from the top-level namespace forofficial images. The / character separatesa user’s repository from the image name.
Once you’ve found the image you want, you can download it with docker pull <imagename>:
You now have an image from which you can run containers.
Starring Repositories
Your repositories can be starred and you can star repositories in return. Starsare a way to show that you like a repository. They are also an easy way ofbookmarking your favorites.
Service accounts
A service account is a Docker ID used by a bot for automating the build pipelinefor containerized applications. Service accounts are typically used in automatedworkflows, and do not share Docker IDs with the members in the Team plan.
To create a new service account for your Team account:
- Create a new Docker ID.
- Create a team in your organization and grant it read-only access to your private repositories.
- Add the new Docker ID to your organization.
- Add the new Docker ID to the team you created earlier.
- Create a new personal access token (PAT) from the user account and use it for CI.
To create a new service account for your Pro account:
- Create a new Docker ID.
- Click Repositories from the main menu.
- Select a repository from the list and go to the Collaborators tab.
- Add the new Docker ID as a collaborator.
- Create a new personal access token (PAT) from the user account and use it for CI.
If you want a read-only PAT just for your open source repos, or to accessofficial images and other public images, you do not have to grant any access permissions to the new Docker ID.
Note
Service accounts are still subject to Docker’s fair pull limit policy. To learn more about these limits, see our Resource Consumption Updates FAQ.
Docker, docker, trusted, registry, accounts, plans, Dockerfile, Docker Hub, webhooks, docs, documentation