Docker Image Principles, Common Pitfalls, and Best Practices for Service Websites

As internal service websites proliferate, server resources become scarce and operations grow more complex, prompting the hand‑off of deployment tasks to dedicated operations engineers. To achieve seamless hand‑off between development, testing, and operations, the team adopted Docker to simplify deployment to an app‑install‑like experience.

Principles for Docker usage emphasize that containers should be stateless, contain only what is needed to run the application, and minimize external dependencies. Persistent data such as databases or file storage should reside outside the container, while the image should be built so that operations only need to execute docker pull , docker run and docker stop .

What to package into the image includes the backend code, the Python runtime (e.g., gunicorn), Nginx (if static file handling is required), MongoDB (or other data services) placed externally, and Supervisor for process monitoring. The author’s practice packs code, Python environment, Nginx, and Supervisor into the image.

Image creation methods are compared: using docker commit after manually configuring a container (complex and uncommon) versus writing a Dockerfile and building with docker build (recommended). The Dockerfile is identified as the core of the containerization workflow.

Faulty Dockerfile example (do not use) is presented with numerous issues:

1. Base image is not minimal – should use a slim Python image.

2. Plain‑text passwords in environment variables.

3. Unmerged RUN statements leading to many image layers.

4. Incorrect use of cd instead of WORKDIR .

5. Ignoring Docker cache semantics, causing stale builds.

6. Installing unnecessary packages that bloat the image.

7. Installing a Python virtual environment inside the image, which is redundant.

8. Including front‑end source code and build tools that are not needed at runtime.

9. Lack of final optimization steps.

The original flawed Dockerfile (shown below) illustrates these problems:

FROM debian
ENV SVN_URL=https://svn.xxx.com/popo_service \
  BASE_PATH=/srv/popo_service \
  CERT_FILE_URL=http://10.0.0.1/files/popo_service.pfx
CERT_PASS=1111
RUN apt-get update
RUN apt-get install --no-install-recommends--no-install-suggests -y net-tools subversion wget npm procps nginx supervisor
RUN npm cache clean --force
RUN npm install -g npm
RUN wget -O /srv/certfile.pfx $CERT_FILE_URL
RUN svn export $ENV $SVN_URL $BASE_PATH \
  --config-optionservers:global:ssl-client-cert-file=/srv/certfile.pfx \
  --config-optionservers:global:ssl-client-cert-password=$CERT_PASS \
  --trust-server-cert-failures=unknown-ca--non-interactive
RUN rm -f /srv/certfile.pfx
RUN cd $BASE_PATH
RUN pip install -r requirement.txt
WORKDIR $BASE_PATH/project/frontend
RUN npm install
RUN npmrun build
RUN rm -rf $BASE_PATH/project/frontend
RUN rm -f /etc/nginx/sites-enabled/default
COPY nginx-popo_service.conf /etc/nginx/conf.d/
COPY supervisor-popo_service.conf /etc/supervisor/conf.d/
EXPOSE 3315
CMD["/usr/bin/supervisord", "-n", "-c", "/etc/supervisor/supervisord.conf"]

Improved Dockerfile addresses the issues by using python:3.7.6-slim-buster as the base, removing SVN checkout and front‑end build steps, consolidating RUN commands with && , installing only necessary packages, and correctly setting WORKDIR . The revised file looks like this:

FROM python:3.7.6-slim-buster
ENV BASE_PATH=/srv/popo_service
EXPOSE 3315
RUN echo "deb http://mirrors.163.com/debian/ buster main\n  deb http://security.debian.org/debian-security buster/updates main\n  deb http://mirrors.163.com/debian/buster-updates main" > /etc/apt/sources.list \
  && apt-get update \
  && apt-get install --no-install-recommends --no-install-suggests -y net-tools procps nginx supervisor
COPY docker/nginx-popo_service.conf /etc/nginx/conf.d/
COPY docker/supervisor-popo_service.conf /etc/supervisor/conf.d/
RUN mkdir -p $BASE_PATH/project/backend && rm -f /etc/nginx/sites-available/default /etc/nginx/sites-enabled/default
COPY project/backend $BASE_PATH/project/backend
COPY project/run.py $BASE_PATH/project/
COPY requirement.txt $BASE_PATH/
CMD ["/usr/bin/supervisord", "-n", "-c", "/etc/supervisor/supervisord.conf"]

Docker image guidelines distilled from the practice:

Prefer the latest official minimal base image that satisfies requirements.

Combine multiple commands into a single RUN using && to reduce layers.

Install system packages first, then add application code.

Copy only the built front‑end artifacts, not source code.

Avoid adding a Python virtual environment inside the image.

Use identical images for testing and production.

Be aware of host‑resource consumption when containers access host resources.

Roles and workflow :

Development : Develop quickly; Docker is not required for coding but should be used for building images.

Testing : Rebuild the image after each code change and test in a fresh container.

Operations : Initial deployment may need coordination on ports and volume mounts; subsequent updates are simple docker pull , docker stop , docker run cycles.

Conclusion : Docker enables a smoother hand‑off between development, testing, and operations, reducing manual configuration and allowing automation. The article encourages sharing experiences and correcting any mistakes in the text.