Skip to content

2026

Setup Alpine Linux VM under Proxmox with Docker

Sample Values and Versions Used:

  • Proxmox Name: pve1
  • Proxmox VM install storage: vm_ct
  • Alpine Version: 3.23.2
  • Alpine VM ID: 888
  • Alpine Server Name: srv-docker-01

1. Download ISO to Proxmox

Get Alpine Docker ISO to Proxmox (assuming pve1 with ISO Images enabled on local)

  • Navigate to (Alpine Linux Downloads)[https://www.alpinelinux.org/downloads/]
  • Right-Click and copy link Standard x86_64 image (for Proxmox install)
    • (Standard 3.23.2)[https://dl-cdn.alpinelinux.org/alpine/v3.23/releases/x86_64/alpine-standard-3.23.2-x86_64.iso]
  • In Proxmox, navigate by clicking through pve1|local|ISO Images:
    • Click Download from URL.
    • Paste https://dl-cdn.alpinelinux.org/alpine/v3.23/releases/x86_64/alpine-standard-3.23.2-x86_64.iso into URL box.
    • Click Query URL.
    • Click Download.

2. Create VM with Alpine Linux

  • Right-Click pve1 and choose Create VM.
    • General
      • VM ID: 888
      • Name: srv-docker-01
      • Click Next.
    • OS
      • Click Next.
    • System
      • Select Qemu Agent
      • Click Next.
    • Disks
      • Storage: vm_ct
      • Disk size (GiB): 256 GB (Min 4GB) # Might want to use 256 GB if hosting something like IMMICH container
      • Click Next.
    • CPU
      • Cores: 2
      • Click Next.
    • Memory
      • Memory (MiB): 4096 (Min 1GB)
      • Click Next.
    • Network
      • Bridge: vmbr0 (default).
      • Click Next.
    • Confirm
      • Click Finish.

3. Start Alpine VM and setup server

3.1 Setup Alpine

root # Default login - no password setup-alpine # Start setup

Options: - keyb : us - variant : us - hostname: srv-docker-01 - network : (eth0) - ip addr : (dhcp) - manual : (n) - new pass: * - retype : * - tz : (utc) - proxy : (none) - mirrors : 1 - setup u : (no) - ssh svr : (openssh) - rootssh : (yes) - sshkey : (none) - disks : sda - diskuse : sys - erase : y

reboot

3.2 Optional: Create Static route for srv-docker-01 using required IP and MAC

ifconfig eth0 | grep -i "HWaddr" # Retrieve MAC as HWaddr

3.3 Unlock Community Repo

/etc/apk/repositories
...
http:// ... /community # Uncomment by removing first `#`
...

3.4 Optional: Update and Install packages (bash, sudo, vim, py3-pip)

Updated package index from the repositories
apk update
Upgrade the Alpine Linux Package Manager (apk-tools) to latest version
apk add --upgrade apk-tools

``` bash title="Upgrade available packages apk upgrade --available 

``` bash title="Synchronize cached writes to persistent storage"
sync

Install bash, sudo, vim, py3-pip packages
apk add --no-cache qemu-guest-agent bash sudo vim py3-pip

3.5 Install QEMU agent for Proxmox

  • QEMU provides ability to report IP to Proxmox
Add packages
apk add --no-cache qemu-guest-agent
add local service to runlevel default
rc-update add local default
Determine available port
ls /dev | grep vport
/etc/local.d/Qemu.start
#!/bin/sh
qemu-ga -d -p /dev/vport1p1 # port can be retrieved via 'ls /dev | grep vport'
Make /etc/local.d/Qemu.start executable
chmod +x /etc/local.d/Qemu.start

4. Install Docker

Install docker with compose (v2) ... no need for v1 (docker-compose)
apk add docker docker-cli-compose
rc-update add docker boot # Add docker service to start on boot
service docker start # Start docker service

Create docker Group with id 1000
addgroup -g 1000 docker
Create docker user with id 1000
adduser -G docker -u 1000 docker
Check created user and group
id docker # show uid, gid, groups
getent group | grep docker # show docker group
cat /etc/passwd | grep docker # show docker user

4.1 Add docker user to sudoers

/etc/sudoers.d/docker
docker ALL=(ALL:ALL) NOPASSWD: ALL
Change permissions to read by user and group
chmod 0440 /etc/sudoers.d/docker

4.2 Optional in case of error: permission denied while trying to connect to the docker API at unix:///var/run/docker.sock

Change permissions for docker.sock to docker group
sudo chown root:docker /var/run/docker.sock

4.3 Create SSH key for docker (log in as docker)

su - docker # run as docker
cd # change to home folder
ssh-keygen -t ed25519 -C "docker@srv-docker-01" -f /home/docker/.ssh/id_ed25519 -N "" # gen key

4.4 Optional: add existing public key for docker user

~/.ssh/authorized_keys
# Paste allowed public key(s)

5. Misc Client Config settings

VIM Config ~/.vimrc
syntax on
set background=dark
set number
colorscheme desert
set nocompatible
set showmode
~/.profile
export PS1="\[\033[0;33m\][\$(date +%Y-%m-%d)][\t]\[\033[0;36m\] [\u\[\033[0;37m\]@\[\033[0;36m\]\h]:\[\033[0;32m\]\w\[\033[0m\] \n$ "
alias ls='ls -la --color=auto'
#alias dps='docker ps  --format "{{.ID}}\t{{.Names}}   \t{{.Status}}\t\t{{.Ports}}"'
alias dps="docker ps -a --format 'table {{.ID}}\t{{.Names}}\t{{.Image}}\t{{.Status}}'"
alias dc='docker compose'
alias dcu='docker compose up -d'
alias dcl='docker compose logs -f'
alias dcd='docker compose down'

# dircolors --print-database
LS_COLORS=$LS_COLORS:'di=1;35:' ; export LS_COLORS
~/.gitconfig
[alias]
        st = status
        lg = log --pretty=format:'%C(red bold)%h%C(reset) - [%C(green bold)%ci%C(reset) %C(magenta bold)%an%C(reset)] %C(yellow bold)%d%Creset %C(white bold)%s%C(reset)'

6. Recurring Updates

Upgrade / update Alpine Linux
apk update
apk add --upgrade apk-tools 
apk upgrade --available
sync

Map Network Drive using Group Policy (GPO)

  1. Create and link a GPO.
  2. Publish a shared folder in Active Directory.
  3. Configure GPO settings for drive mapping.

Prerequisites

  • Admin privileges on AD domain controller.
  • AD Org Units (OUs)
  • Shared Network Folder
    • Accessible via UNC Path (\servername\sharename)
    • Have appropriate permissions (Ex. Read / Write)
  • Access to Group Policy Management Console (GPMC) to create new GPOs, Link GPOs to OUs or groups, Edit drive mapping preferences
  • Drive Letter List

Main Steps

Step 1: Create a Group Policy Object (GPO)

A new GPO is required to define the settings for network drive mapping. Here’s how to create it:

  1. Log in to the Domain Controller Use an account with administrative privileges. Open the Server Manager dashboard.
  2. Access Group Policy Management Navigate to Tools > Group Policy Management from the Server Manager.
  3. Expand Your Domain Name Locate your domain in the left-hand navigation pane. Expand it to reveal the Group Policy Objects folder.
  4. Create a Copy of the Default Domain Policy Drag the Default Domain Policy to the Group Policy Objects container. When prompted, click OK to authenticate the copy process.
  5. Rename the Copied GPO Right-click the copied policy and select Rename. Use a descriptive name, such as “Map Accounts Share.”

At this stage, you have created a new GPO, which will later contain the drive mapping settings.

To apply the policy, you need to link it to the relevant OU where the users or computers reside.

  1. Drag the GPO to the Target OU Locate the OU (e.g., HR, IT, or Sales) in your Active Directory structure. Drag and drop the newly created GPO onto the target OU.
  2. Confirm the Link Click OK when prompted to authenticate the linking process.Background Image
  3. Verify the Link Expand the target OU in the Group Policy Management Console (GPMC). Ensure the GPO is listed under the Linked Group Policy Objects section.

This step ensures that the settings defined in the GPO will apply only to the specified OU.

Step 3: Publish the Shared Folder in Active Directory

Before mapping the drive, the shared folder must be published in Active Directory.

  1. Log in to the Domain Controller Use administrative credentials. Open the Server Manager dashboard.
  2. Open Active Directory Users and Computers Navigate to Tools > Active Directory Users and Computers.
  3. Select the Target Container Locate the container (e.g., Computers, Users, or a custom container) where you want to publish the share.
  4. Create a New Shared Folder Right-click the container, select New, and choose Shared Folder. The New Object – Shared Folder window will appear.
  5. Enter the Folder Details Name: Assign a name for the shared folder (e.g., “HR Shared Files”). Network Path: Enter the path to the folder in the format \ServerName\ShareName.
  6. Click OK Save the shared folder details.

Publishing the folder makes it discoverable by the Group Policy Management Console for mapping.

Step 4: Configure the GPO to Map Network Drives

With the shared folder published, configure the GPO to map the drive.

  1. Edit the GPO In Group Policy Management, right-click the GPO created earlier (e.g., “Map Accounts Share”) and select Edit.
  2. Navigate to Drive Maps In the Group Policy Management Editor: Go to User Configuration > Preferences > Windows Settings > Drive Maps.
  3. Add a New Mapped Drive Right-click Drive Maps and choose New > Mapped Drive. This opens the New Drive Properties window.Background Image
  4. Configure General Settings In the General tab, set the following: Location: Click the three-dot icon and select the shared folder you published. Reconnect: Check this box to ensure the drive reconnects after each login. Drive Letter: Choose a specific letter or use the option “Use the first available starting at” to let Windows assign one automatically.
  5. Configure the Common Tab Switch to the Common tab and check these options: Run in logged-on user’s security context: Ensures the drive maps under the user’s credentials. Item-level Targeting: Allows targeting based on user or computer attributes.
  6. Set Item-Level Targeting Click the Targeting button to define conditions: New Item: Specify the criteria (e.g., user belongs to a specific OU or group). Confirm and apply the settings.
  7. Save and Apply Click Apply and OK to save the configurations.
  8. Force Group Policy Update on Clients Run the command gpupdate /force on a client machine to apply the new settings immediately.

Step 5: Verify the Mapped Drive

  1. Restart a Client Machine Reboot a machine within the target OU.
  2. Check Mapped Drives Open File Explorer and navigate to This PC. Confirm that the mapped drive appears with the assigned drive letter and shared folder name.

Troubleshooting Common Issues

Even with a properly configured Group Policy Drive Mapping, you may encounter issues that prevent mapped drives from appearing or functioning correctly. Use this troubleshooting guide to identify and resolve common problems.

1. Group Policy Object (GPO) Not Applying

Symptoms: The mapped drive does not appear on client machines.

Solution:

  • Verify that the GPO is correctly linked to the intended Organizational Unit (OU).
    • Open Group Policy Management and confirm the GPO is listed under the Linked Group Policy Objects for the target OU.
  • Check if the client machines are part of the domain and reside in the correct OU.
  • Ensure the GPO is enabled and not blocked by inheritance settings.
    • In the GPO’s properties, confirm that Enforced is selected, if necessary.

Additional Check:

  • Run gpresult /h gpresult.html on the client machine to generate a detailed report.
    • Open the report in a browser and look for the GPO under Applied Group Policy Objects.
    • If it’s missing, check the GPO link and replication settings.

2. Incorrect Network Drive Mapping

Symptoms: The drive maps to the wrong location or with the wrong drive letter.

Solution:

  • Double-check the Location field in the GPO configuration:
    • Ensure it points to the correct shared folder path (e.g., \ServerName\ShareName).
  • Confirm that the assigned drive letter is not already in use on the client machine.
    • Use the New Drive Properties window in GPO to select an available drive letter.

Additional Check:

  • Test the shared folder manually on the client machine:
    • Open Run (Windows + R) and type the network path (e.g., \ServerName\ShareName).
    • Verify that the folder is accessible.

3. Permissions Issues

Symptoms: Users see an error message or cannot access the mapped drive.

Solution:

  • Review the permissions of the shared folder:
    • In the folder’s properties, go to the Security tab.
    • Ensure the target users or groups have the required permissions (e.g., Read or Full Control).
    • Verify the permissions on the Sharing tab as well.
  • Check that the shared folder is accessible from client machines:
    • Use a test account within the targeted group to verify access.

4. Group Policy Updates Not Propagating

Symptoms: Changes to the GPO are not reflected on client machines.

Solution:

  • Manually force a Group Policy update on the affected client machine:
    • Open Command Prompt as an administrator.
    • Run gpupdate /force.
  • Confirm that the Group Policy service is running on the client machine:
    • Open Services and look for Group Policy Client.
    • If stopped, restart the service.

Additional Check:

  • Verify network connectivity between the client and domain controller.
    • Run ping DomainControllerName to test connectivity.

5. Mapped Drive Not Reconnecting After Restart

Symptoms: The drive disappears after the user logs out or reboots.

Solution:

  • In the New Drive Properties window under General, ensure the Reconnect box is checked.
  • Confirm that the option Run in the logged-on user’s security context is enabled in the Common tab.
  • Check for any conflicting login scripts that might override the GPO settings.

6. Issues with Item-Level Targeting

Symptoms: Mapped drives are not applied to specific users or groups.

Solution:

  • Review the item-level targeting conditions in the GPO:
    • Open the Common tab in the New Drive Properties window.
    • Click the Targeting button and ensure the conditions (e.g., user or group membership) are correct.
  • Test the targeting rules with a sample account to verify accuracy.

Additional Check:

  • If the targeting involves an OU, confirm that the user or computer is placed in the correct OU within the Active Directory.

7. Slow Login Due to Drive Mapping Delays

Symptoms: Users experience slow login times when the drive mapping is applied.

Solution:

  • Optimize the GPO by reducing unnecessary policies linked to the same OU.
  • Check the performance of the shared folder’s hosting server.
    • High latency or resource limitations on the server can delay drive mapping.
  • Enable asynchronous processing for drive mappings:
    • In the Common tab, select Run in the logged-on user’s security context to speed up application time.

8. Network Issues Affecting Mapping

Symptoms: Drives fail to map when users log in from remote locations or unstable networks.

Solution:

  • Ensure VPN users can access the shared folder.
    • Verify that the network path (e.g., \ServerName\ShareName) is reachable over the VPN.
  • Consider using offline files for critical shares to ensure access even when disconnected.
  • Recommend upgrading to a cloud-based solution like V2 Cloud for remote users to avoid dependency on local network drives.

References