Container Deployment and Use Guide

2025-11-26

This guide will introduce how to install and use Docker on Quectel Pi H1 devices for containerized application deployment.

Introduction

Docker is a lightweight containerization technology with the following features:

  • Easy Management: Use Docker commands to manage containers and images, with dependency isolation, simplifying deployment processes.
  • Cross-Platform: Supports Windows, macOS, and Linux systems, enabling containers to run and deploy on multiple platforms.
  • Portability: Achieve environment consistency through Dockerfiles and images, facilitating quick migration and deployment across different machines or cloud platforms.
  • Efficient Resource Utilization: Based on containerization technology, sharing the host kernel, with low resource consumption and fast startup speed, suitable for microservices architecture.

Prerequisites

Before installing Docker, please ensure the following conditions are met:

System Requirements:

  • Quectel Pi H1 device is booted normally
  • Connected to the network (for downloading Docker images)
  • Has root or sudo privileges

Network Preparation:

  • Ensure the device can access the internet (for pulling images from Docker Hub)
  • If in mainland China, you may need to configure Docker image sources to speed up downloads

Disk Space:

  • Ensure sufficient disk space for storing Docker images and containers (recommended at least 2GB free space)

Installation Steps

Update Package List and Install Docker

sudo apt update
sudo apt install docker.io

Configure iptables

Docker requires iptables to be configured to work properly. Execute the following commands:

sudo update-alternatives --set iptables /usr/sbin/iptables-legacy
sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy

After executing the above commands, you need to restart the system for the configuration to take effect:

sudo reboot

Verify Installation

After the system restarts, verify that Docker is installed successfully:

docker --version

If the terminal outputs information similar to the following, the installation is successful:

Docker version 26.1.5+dfsg1, build a72d7cd

Add User Permissions

To run Docker commands without using sudo, you can add the current user to the Docker user group:

sudo usermod -aG docker $USER

After adding, you need to start the Docker service and log out and log back in, or restart the system for the configuration to take effect:

# Start Docker service
sudo systemctl start docker

# Enable Docker service to start on boot
sudo systemctl enable docker

After logging back in, you can verify with the following command:

docker ps

If you can execute it without using sudo, the configuration is successful.

Configure Docker Image Sources (Optional)

If you are in mainland China, accessing Docker Hub may be slow. You can configure domestic image sources to speed up downloads. Use the following command to create the /etc/docker/daemon.json file:

sudo mkdir -p /etc/docker
sudo sh -c 'echo "{
  \"registry-mirrors\": [
    \"https://docker.mirrors.ustc.edu.cn\",
    \"https://hub-mirror.c.163.com\"
  ]
}" > /etc/docker/daemon.json'

After configuration, restart the Docker service:

sudo systemctl restart docker

Usage

Tips:

  • Image: A read-only template containing an application and its runtime environment (including dependencies, libraries, configuration files, etc.).
  • Container: A running instance of an image, providing an executable environment based on the image, containing the application and all dependencies, but isolated from the host system.

View Help

Use Docker's built-in help command to view usage information for all commands:

docker --help
docker <command> --help

For example:

docker run --help
docker ps --help

View Docker System Information

Use the docker info command to view Docker system information, including version, system configuration, storage driver, network configuration, etc.:

docker info

Basic Operations

Pull Docker Images

Use the docker pull command to pull the required application images from Docker Hub:

docker pull <image_name>

# Example: Pull the latest hello-world image
docker pull hello-world

Run Docker Containers

Use the docker run command to run containers based on the pulled images:

# Run hello-world container (exits immediately after running)
docker run hello-world

# Run with container name
docker run --name my-hello hello-world

Note: The hello-world image is a demonstration image that prints a welcome message and then exits. For interactive operations or continuously running containers, you can use other images, for example:

# Run container interactively (using ubuntu image)
docker run -it ubuntu:20.04 /bin/bash

# Run container in background (using ubuntu image)
docker run -d --name mycontainer ubuntu:20.04 tail -f /dev/null

View Containers and Images

# View running containers
docker ps

# View all containers (including stopped ones)
docker ps -a

# View local images
docker images

Stop and Remove Containers

# Stop container
docker stop <container_id>

# Remove container
docker rm <container_id>

# Remove image
docker rmi <image_id>

Save Container as New Image

If you have modified the container, you can use the docker commit command to save the container as a new image:

docker commit <container_id> <new_image_name>

For example:

# View container ID
docker ps -a

# Save container as new image
docker commit <container_id> my-hello-world:v1

Data Volumes

Data volumes are used to share data between containers and the host. Even if a container is deleted, the data in the volume is still preserved.

Create Data Volume

docker volume create myvolume

Run Container with Data Volume

# Using hello-world image (Note: hello-world exits immediately after running)
docker run -v myvolume:/data hello-world

# For containers that need to run continuously, you can use other images
docker run -d -v myvolume:/data ubuntu:20.04 tail -f /dev/null

The above command mounts the volume myvolume to the /data directory in the container.

Directly Mount Host Directory

# Using hello-world image
docker run -v /host/path:/container/path hello-world

# For containers that need to run continuously, you can use other images
docker run -d -v /host/path:/container/path ubuntu:20.04 tail -f /dev/null

Mounts the host's /host/path directory to the /container/path directory in the container.

Manage Data Volumes

# View volume list
docker volume ls

# View volume details
docker volume inspect myvolume

# Remove data volume
docker volume rm myvolume

Port Mapping

Port mapping allows mapping ports inside the container to ports on the host, enabling external access to services inside the container.

Basic Port Mapping

docker run -d -p 8080:80 nginx

Maps port 80 in the container to port 8080 on the host.

Port Mapping with Specific Host IP

docker run -d -p 127.0.0.1:8080:80 nginx

Only allows access through 127.0.0.1 on the host.

View Port Mappings

docker port <container_id>

Environment Variables

Environment variables can be passed to applications inside containers when running containers.

Set Environment Variables Using -e Parameter

docker run -d -e MYSQL_ROOT_PASSWORD=password mysql:5.7

Read Environment Variables from File

# Using hello-world image
docker run --env-file .env hello-world

# For containers that need to run continuously, you can use other images
docker run -d --env-file .env ubuntu:20.04 tail -f /dev/null

Container Networks

Docker provides multiple network modes for communication between containers.

Create Custom Network

docker network create mynetwork

Connect Containers to Network

# Using hello-world image
docker run --network mynetwork --name container1 hello-world

# For containers that need to run continuously, you can use other images
docker run -d --network mynetwork --name container2 ubuntu:20.04 tail -f /dev/null

Containers connected to the same network can communicate with each other using container names.

Manage Networks

# View network list
docker network ls

# View network details
docker network inspect mynetwork

# Disconnect container from network
docker network disconnect mynetwork container1

Container Restart Policies

You can set restart policies for containers to automatically restart them after they exit:

# Using hello-world image (Note: hello-world exits immediately after running)
docker run --restart=always --name my-hello hello-world

# For containers that need to run continuously, you can use other images
docker run -d --restart=always --name mycontainer ubuntu:20.04 tail -f /dev/null

Restart policy options:

  • no: Do not automatically restart (default)
  • always: Always restart
  • on-failure: Restart only on abnormal exit
  • unless-stopped: Always restart unless manually stopped

Container Resource Limits

You can limit the CPU and memory resources used by containers:

Limit Memory Usage

# Using hello-world image
docker run -m 512m hello-world

# For containers that need to run continuously, you can use other images
docker run -d -m 512m ubuntu:20.04 tail -f /dev/null

Limits the container to use at most 512MB of memory.

Limit CPU Usage

# Using hello-world image
docker run --cpus="1.5" hello-world

# For containers that need to run continuously, you can use other images
docker run -d --cpus="1.5" ubuntu:20.04 tail -f /dev/null

Limits the container to use at most 1.5 CPU cores.

Other Common Commands

  • View container logs:

    docker logs <container_id>
docker logs -f <container_id>  # Real-time view

  • Enter a running container:

    docker exec -it <container_id> /bin/bash

  • View container resource usage:

    docker stats
docker stats <container_id>  # View specific container

  • View container details:

    docker inspect <container_id>

  • Copy files:

    docker cp /host/path/file.txt <container_id>:/container/path/  # Copy to container
docker cp <container_id>:/container/path/file.txt /host/path/  # Copy from container

  • Pause/Unpause container:

    docker pause <container_id>
docker unpause <container_id>

  • Clean up unused resources:

    docker system prune -a

Common Issues

Cannot Access Docker Hub, Image Pull Fails

Problem: In mainland China, direct access to Docker Hub may be slow or fail.

Solution:

  • Configure Docker image sources (refer to the "Configure Docker Image Sources" section in Installation Steps)
  • Use a proxy server
  • Use domestic image repositories such as Alibaba Cloud, Tencent Cloud, etc.

Permission Denied When Executing Docker Commands

Problem: When executing commands like docker ps, you get a permission denied error.

Solution:

  • Ensure the user has been added to the Docker user group: 
    sudo usermod -aG docker $USER
  • Log out and log back in, or restart the system
  • If it still doesn't work, you can use sudo to execute commands (not recommended)

Docker Service Cannot Start

Problem: When executing docker ps, you get Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

Solution:

  • Check Docker service status:

    sudo systemctl status docker

    If the service is not running, it will show inactive (dead) status.

  • Start Docker service:

    sudo systemctl start docker

    After starting, check the status again to confirm the service is running.

  • Enable Docker service to start on boot:

    sudo systemctl enable docker

    This ensures Docker service starts automatically after system reboot.

  • Check Docker socket file permissions:

    ls -l /var/run/docker.sock

    If the file does not exist or has incorrect permissions, restart the Docker service:

    sudo systemctl restart docker

  • Check if user is in docker group:

    groups

    If docker is not in the output, you need to add the user to the docker group (refer to the "Add User Permissions" section in Installation Steps).

  • Ensure iptables is properly configured:
    If Docker service fails to start, it may be an iptables configuration issue. Refer to the "Configure iptables" section in Installation Steps.

  • View Docker service logs:

    sudo journalctl -u docker -n 50

    View detailed error messages to help identify the problem.

Container Exits Immediately After Starting

Problem: After using docker run to start a container, the container exits immediately.

Solution:

  • Check container logs: 
    docker logs <container_id>
  • Run container in interactive mode: 
    docker run -it ubuntu:20.04 /bin/bash
  • Ensure there is a continuously running process in the container, or use tail -f /dev/null to keep the container running

How to Clean Up Unused Docker Resources

Problem: Docker is using a lot of disk space.

Solution:

  • Clean up unused containers, networks, and images: 
    docker system prune -a
  • Clean up unused data volumes: 
    docker volume prune
  • Manually delete unnecessary images and containers

Container Cannot Access External Network

Problem: The container cannot access the internet.

Solution:

  • Check the host's network connection
  • Check Docker network configuration: 
    docker network ls
docker network inspect bridge
  • Restart Docker service: 
    sudo systemctl restart docker

Port Mapping Not Working

Problem: Port mapping is configured, but cannot access container services from outside.

Solution:

  • Check if port mapping is correct: 
    docker port <container_id>
  • Check firewall settings to ensure ports are not blocked
  • Check if services inside the container are running normally: 
    docker exec -it <container_id> ps aux

Data in Volume Lost

Problem: After deleting the container, data in the volume is also lost.

Solution:

  • Ensure you use named volumes instead of anonymous volumes: 
    docker run -v myvolume:/data hello-world
  • Do not use the -v parameter when deleting containers (this will also delete associated volumes)
  • Regularly backup important data

How to View Container Resource Usage

Solution:

# View resource usage of all containers in real-time
docker stats

# View resource usage of specific container
docker stats <container_id>

Containers Do Not Auto-Start After System Reboot

Problem: After system reboot, previously running containers do not start automatically.

Solution:

  • Use --restart=always parameter when running containers:

    # Using hello-world image
docker run --restart=always --name my-hello hello-world

# For containers that need to run continuously, you can use other images
docker run -d --restart=always --name mycontainer ubuntu:20.04 tail -f /dev/null

  • For existing containers, update restart policy:

    docker update --restart=always <container_id>

Through the above steps and issue solutions, you can successfully install and use Docker on Quectel Pi H1 devices, making it convenient to deploy and manage containerized applications.