I was looking for documentation for Docker recently to help someone understand how they were trying to set up their app, and most of what I came across was either too little information or much more detailed than what I was looking for. So I’m making this for those who are somewhere in the middle and trying to bridge the gap. If you went through my Nextcloud setup and had some issues, this will help you understand what you were doing and will enable you to troubleshoot it a bit on your own.

First you need to understand what docker IS though. Docker is an engine that allows you to containerize applications into their own space, without affecting the rest of the system. If you’re familiar with virtualization you already somewhat understand the concept, only you don’t have to spin up and build a whole virtual machine, this application actually runs using your host kernel and resources. It just creates kind of its own file system space that is separate from your host.

This post is going to strictly cover Linux because it’s 1:1 on how the containers are managed. You can run Docker on Windows and Mac too, but there are other factors at play. I’m not going into that for the sake of simplicity.

Now, let’s look at a real practical use. I’m going to use the Nextcloud image that we used in my  Personal Cloud  post now. You’ll notice that these images all mention tags, this is just the version number. The actual Nextcloud container supports putting tags on to bind your server to a particular version number, but the Linux Server people have theirs set up a bit more simply. We’ll just stick with latest.

Ok, now let’s look at the basic command:

docker run -d \
  --name=nextcloud \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Europe/London \
  -p 443:443 \
  -v /path/to/appdata:/config \
  -v /path/to/data:/data \
  --restart unless-stopped \
  ghcr.io/linuxserver/nextcloud:latest

It’s important to note, the backslash (\) is a word wrap indicator in Linux. So you can open a text editor and put your command in as many lines as you want, just put that at the end. In reality that command reads as:

docker run -d --name=nextcloud -e PUID=1000 -e PGID=1000 -e TZ=Europe/London -p 443:443 -v /path/to/appdata:/config -v /path/to/data:/data --restart unless-stopped ghcr.io/linuxserver/nextcloud:latest

Just, don’t put spaces AFTER the slash, the command will break entirely.

The ‘-d’ in the command just means to run as detached, otherwise you would be running your command and it will run in real time until you hit CTRL^C which will kill the process as well. If you plan on your image running by itself, you should make sure to add this option.

Another important thing to note is the PUID and PGID, which is entirely dependent on your system. If you are the only admin there is a 99% chance that this will be 1000 because there are other types of “system accounts” that are used prior to that. You can verify by typing this into your command line (do not invoke sudo, run as yourself):

id $user

You will see the uid and gid come back with a numerical value and a name value. This will also probably show you all the gid’s that you are a part of. When you set these values, you are effectively saying: “Whatever the admin account is in the container is equal to this account on the host.” This will effectively declare that you are the owner of that container. This is really useful in creating persistent data, which we’ll get to in a bit. You’ll notice 1000 was taken by autologin when I set up this machine, and my GID is 1001, this is precisely why this is an important step. Don’t worry though, I have a disk encryption passphrase that is supposed to take a quindecillion years to break (90 zeros).

Name and time zone are relatively self-explanatory, if you don’t specify a name it will generate one using two random words. Time zone is UNIX epoch format so you’ll likely need to consult a list like this in order to find that. I’ll cheat a bit though and tell you that CST is America/Chicago. Skipping to the end, you’ll see the restart parameter, which should also be pretty self-explanatory. I pick unless-stopped instead of always (another option) because if there are issues and you need to troubleshoot it’s much easier when the container just stays off when you want it to.

Next comes the part that can trip people up. This is the bindings that relate between the host and container. Now obviously you do not have an actual folder path to /path/to/data. You would instead maybe have that data in /mnt/nextcloud/data so you would fill in your own values. The important part is you figure out which side is the host and container. I am going to borrow the “righty tighty” line and just remember that containers are TIGHT-knit isolated spaces. I’ll let you look back at the command and see if you can visualize that.

Did you get it? Ok cool so /mnt/nextcloud/data on my host has some files (ls -la will show permissions and hidden), if I enter the container using:

docker exec -it nextcloud bash

Then I view the files located at /data they should be precisely the same thing. But if you look in your container, you won’t see yourself as the user, you’ll see “abc” because that is the admin account they use inside the container.

This is where that UID stuff comes into play. Now abc owns the data as far as the container is concerned, and you have translated that account to mean your own on the host, so now you running that container, give yourself permission to manipulate the data. Otherwise you’ll have probably docker owning the data (960) and that isn’t even a real user.

The port is where you actually go to get to the admin side. You can keep 443 as the port, OR if you use a lot of apps with a reverse proxy, you might specify something like this:

-p 8081:80 \
-p 4341:443 \

Your container will then use the values as it’s prompted by the reverse proxy but you can get to it locally using the IP and specified port in order to get to that point.

That’s essentially the basic makeup of how Docker works. There is a lot more to it, even my personal cloud post mentions creating a network – but if you just want to get going running your own containerized apps either by self-hosting or developing, you’ll be going in the right direction.