How to install an agent on a local standalone docker install?

[TheLargeCactus]

Ask a Question!

I currently have docker setup in a homelab system, and have been using it well for a few years. I recently added a GPU to this lab to start doing some research with it, but want to be able to allow access to the GPU for a container container a jupyter server so that I can use the GPU inside a jupyter notebook. I am trying to enable access to the GPU, but I see in the portainer UI that I can only do that by allowing host management through portainer agent. The agent container can be started up easily enough, but I can't specify localhost or the unix socket in the new environment, and I can't delete my default local environment and replace it with one that points to the agent. How can I proceed? The docs seem for this seem to be leading me in a loop.

I'm using Ubuntu 24.04, Docker 28.3.3, Portainer 2.27.9 LTS, and Portainer Agent 2.22.0

[Nick-Portainer]

Hi @TheLargeCactus Can you walk me through the steps you are going through? If you need to add a new environment via an agent, you simply deploy the agent on that host and in the Portainer UI add the new environment pointing to the IP of that new environment/host.

Make sure the agent run command uses -v /:/host https://docs.portainer.io/user/docker/host/setup#enable-host-management-features

[TheLargeCactus]

Hi Nick, and thanks for taking the time to reach out. Normally this wouldn't be any kind of problem, but I'm currently trying to install the portainer agent on the same docker instance that the portainer server is running on. I only have the one homelab, so I can't separate the portainer server into a different docker instance. If I try to add the portainer agent as a new environment on the same instance, I would have to create an entirely different environment that points to the same place as the local docker environment.

The steps I tried to take:

1. Install Docker on the local Ubuntu system
2. Add portainer-ce to the docker instance via the terminal
3. Add portainer agent to the docker instance via the terminal (same result if using portainer to add the agent as a new container to the same instance)
4. Try to replace the local docker environment. It's not possible to do so, and creating a new environment means I've duplicated the same local environment into two definitions, which seems counterintuitive, especially given that I already have containers running in the original local environment, it would be odd to duplicate in that way.

[Nick-Portainer]

Hi @TheLargeCactus,

You don’t need to run a Portainer Agent on the same host just to use your GPU.
If the host that runs Portainer Server already has the NVIDIA driver and the NVIDIA Container Toolkit installed, you can give GPU access to any container by declaring it in the docker-compose.yml.

services:
  jupyter:
    image: your-jupyter-image
    device_requests:
      - driver: nvidia
        count: all          # or a specific number
        capabilities: [gpu]

More details are in Docker’s GPU guide: https://docs.docker.com/compose/how-tos/gpu-support/

Hope that clears it up.

[TheLargeCactus]

Hey Nick, I agree that this could be done with docker itself, but I was wondering if it was possible to achieve with portainer. I like the convenience of using the web UI instead of needing to ssh into my host and running a few docker commands to get the same thing done. It feels bad to have to go outside the convenient management of portainer and seems like it would be antithetic to portainer's purpose.

[Nick-Portainer]

Hey @TheLargeCactus You can 100% still use this within the WebUI, which is what I was meaning. Portainer is interacting with the Docker engine so if you can run it locally you can do it via Portainer. Portainer itself will not be able to configure your host to be able to use the GPU though, you will need to do this via the CLI. Once it's setup you can deploy containers via Portainer using the GPU