龙讯旷腾 pwmat Wiki

本页面只读。您可以查看源文件，但不能更改它。如果您觉得这是系统错误，请联系管理员。
====== Using Docker ======

<wrap tip>
This page is a collection of Docker commands you'll use day-to-day while running the PWstudio container — from basic concepts and a command cheat-sheet, to operations specific to the PWstudio container (viewing logs, entering the container, transferring files, starting at boot), plus fixes for the most common errors. If you're looking for something specific, just search this page for a keyword — you don't need to read it all. We recommend copying and pasting every command, and being careful not to copy the command prompt along with it.
</wrap>

===== 1. Basic concepts =====

A quick rundown of a few concepts, to make the commands below easier to follow:

  * **Image**: think of this as a packaged "install disc" containing everything needed to run PWstudio (the OS, dependencies, programs, etc.) — for example, ''ccr.ccs.tencentyun.com/lxkt/qflowgpu:latest'' is the PWstudio GPU image. An image itself is read-only and doesn't change no matter how you use it.
  * **Container**: this is an instance of an image that's actually "running" — like an actual running machine built from that install disc. The names "qflowcpu" and "qflowgpu" that you normally see are just names given to this container (set via the ''--name'' parameter). One image can be used to start multiple containers, but in this guide you'll typically only run one at a time.
  * Important: **removing a container (''docker rm'') does not remove the image** — you can create a new container from the same image afterward. However, **any data generated inside the container that isn't mapped to the host machine will be lost once the container is removed**, so make sure important data either lives in a directory mapped out with the ''-v'' option, or is backed up ahead of time.

===== 2. Command cheat-sheet =====

Most of the commands below require root privileges — if you see "permission denied," just add ''sudo'' in front of the command.

==== 2.1 Check container status ====

<code bash>
# See containers that are currently running
sudo docker ps

# See all containers, including stopped ones
sudo docker ps -a
</code>

''docker ps'' only shows containers that are currently running; if a container was previously stopped (e.g. after a host reboot), you need to add ''-a'' to see it. The ''STATUS'' column shows "Exited ..." for stopped containers, and "Up ..." for running ones.

==== 2.2 List local images ====

<code bash>
sudo docker images
</code>

Lists every image already downloaded onto the current server, including its name, version tag (TAG), size, and so on.

==== 2.3 Start / stop / restart a container ====

<code bash>
# Start a container that already exists but is currently stopped
sudo docker start qflowcpu

# Stop a running container
sudo docker stop qflowcpu

# Restart a container (equivalent to stop followed by start)
sudo docker restart qflowcpu
</code>

Replace ''qflowcpu'' with the actual name of your container (for the GPU version it's usually ''qflowgpu'' — you can check with ''docker ps -a'' from 2.1). All three of these commands operate on a container that **already exists**; they don't re-pull the image, and they don't lose any data inside the container.

<wrap important>
After the host machine (server) reboots, a previously-created container **won't automatically disappear, but it also won't necessarily start automatically** — that depends on whether an auto-restart option was set when the container was created. If the web page won't load after a reboot, first run ''sudo docker ps -a'' to check whether the container is in the "Exited" state. If it is, just run ''sudo docker start qflowcpu'' (using your own container name) to start it manually — you don't need to run the whole ''docker run'' command again.
</wrap>

==== 2.4 Get inside the container ====

<code bash>
# Enter the container and open an interactive shell
sudo docker exec -it qflowcpu bash

# When you're done, exit back to the host (this does not stop the container)
exit
</code>

This is the most common way to troubleshoot: once inside, it's just like logging into a separate Linux system, where you can look at files and run commands. Running ''exit'' just closes this interactive session — the container itself keeps running in the background, unaffected.

==== 2.5 View container logs ====

<code bash>
# View the container's recent log output (messages printed by the program inside the container)
sudo docker logs qflowcpu

# Only show the last 100 lines - handy to avoid a huge wall of text
sudo docker logs --tail 100 qflowcpu

# Follow the logs in real time (like tail -f); press Ctrl+C to exit
sudo docker logs -f qflowcpu
</code>

When the web page won't load, or a submitted job errors out, and you're not sure why — **checking the container logs first is usually the fastest way to figure out what's going on**, since a lot of error messages get printed here directly.

==== 2.6 Copy files between the container and the host ====

<code bash>
# Copy a file from the host machine into the container
sudo docker cp /path/on/host/filename qflowcpu:/path/in/container/

# Copy a file from the container to the host machine
sudo docker cp qflowcpu:/path/in/container/filename /path/on/host/
</code>

This isn't something you'll use often (normally you'd upload/download data through the web page or via SSH/SFTP instead — see [[en:pwstudio:mobaxterm|the MobaXterm beginner tutorial]]), but if you ever need to move a single file directly between the host and the container, this command does the job without installing anything extra.

==== 2.7 Check container resource usage ====

<code bash>
sudo docker stats qflowcpu
</code>

Shows the container's current CPU, memory, etc. usage in real time. If you suspect a calculation is running slowly or erroring out due to insufficient resources, check here — press ''Ctrl+C'' to exit.

==== 2.8 Pull (download) an image ====

<code bash>
sudo docker pull ccr.ccs.tencentyun.com/lxkt/qflowcpu:latest
</code>

Downloads the PWstudio image from the remote registry to your local machine. If you already have the same version locally, it will quickly report "already up to date"; if not, it will download the full image, which may take a few minutes to over ten minutes depending on your network speed — please be patient.

==== 2.9 Completely remove a container / image ====

<code bash>
# Remove a container (it must be stopped first, or you'll get an error — run docker stop first if needed)
sudo docker rm qflowcpu

# Remove an image (note: if any container is still using this image, remove that container first)
sudo docker rmi ccr.ccs.tencentyun.com/lxkt/qflowcpu:latest
</code>

<wrap important>
''docker rm'' only removes the container — the "running instance" — it doesn't remove the image itself, nor any data files mounted onto the host machine via the ''-v'' option. However, any files inside the container that weren't mapped out will disappear along with it — make sure you're certain before deleting, and back up anything important beforehand.
</wrap>

===== 3. Fixing a container name conflict (the most common error) =====

If you see an error like this when re-creating or restarting a container:

<code bash>
docker: Error response from daemon: Conflict. The container name "/qflowcpu" is already in use by container "02919a65bee0615eb8960ff7f9ee0f54c8f2924cf6f692fcd8a9191f1356ead3". You have to remove (or rename) that container to be able to reuse that name.
</code>

This means: **the container name you're trying to create (e.g. "qflowcpu") is already taken by an existing container**. Docker doesn't allow two containers to share a name, so you need to deal with the old one before creating a new one. Follow these steps in order:

  - **Confirm it**: run ''sudo docker ps -a'' and look for a row with ''qflowcpu'' under ''NAMES'', matching the name in the error message.
  - **Stop the old container**: ''sudo docker stop qflowcpu''
  - **Remove the old container**: ''sudo docker rm qflowcpu''
  - **Re-create it**: run the ''docker run'' command from the "Start the container" section of your installation guide again (see [[en:pwstudio:quickstart_gpu#Start the container|Start the container]] or [[en:pwstudio:quickstart_cpu#Start the container|Start the container]]).

If all you want is to restart the container (not rename it or switch image versions), you don't need to go through all that — just run ''sudo docker restart qflowcpu'', no need to stop, remove, and re-run.

===== 4. Common errors =====

==== 4.1 Port already in use ====

<code bash>
Error response from daemon: driver failed programming external connectivity on endpoint qflowcpu: Bind for 0.0.0.0:80 failed: port is already allocated
</code>

This means port 80 (or 81, 2297, etc.) on the host machine is already being used by something else — commonly because another web service is already installed on the server (e.g. nginx/apache), or because an old container that's still running is holding onto that port. Run ''sudo docker ps -a'' to check whether another container is using the port in question, resolve the conflict (stop the service using the port, or remove the old container), and then start it again.

==== 4.2 Out of disk space ====

<code bash>
no space left on device
</code>

This means the server is running low on disk space. Run the commands below to clean up unused Docker images and temporary files that have piled up over time (this won't affect images and containers currently in use):

<code bash>
sudo docker system df      # First check how much space Docker is using
sudo docker system prune   # Clean up unused images, containers, networks, etc.
</code>

When you run ''docker system prune'', it will ask you to confirm first — type ''y'' and press Enter to confirm.

==== 4.3 permission denied ====

<code bash>
permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock
</code>

This means your current login user doesn't have permission to use Docker directly. The simplest fix is to add ''sudo'' in front of the command. If you'd rather not type sudo every time, see the "Allow a non-root user to run Docker" section in the installation guide (which adds you to the ''docker'' group) — you'll need to log out and back in once for that to take effect.

==== 4.4 Other issues with job submission from the command line ====

If the error is happening inside the container itself (e.g. submitting a job with slurm), it isn't related to Docker — see [[en:pwstudio:qa|PWstudio installation FAQ]] or [[en:pwstudio:cmd|Submitting PWstudio jobs from the command line]].

~~DISCUSSION:off~~