Setting up Gitea in WSL with Docker Compose often results in an empty host volume because the bind mount path does not exist or lacks proper permissions. This guide resolves the issue by ensuring the directory structure is correctly created and mapped, preventing data loss and container startup failures while maintaining secure file access on your Windows host.
Understanding the Empty Volume Problem
When you configure a
docker-compose.yml file for Gitea, the service requires persistent storage for its database, repositories, and configuration files. The standard approach uses a bind mount to map a directory from your Windows host (accessible via WSL) to the container’s internal paths. If this mapping fails silently or points to an uninitialized location, the container may start but appear to have no data, or it may fail entirely due to permission errors.
The core of the issue usually lies in how WSL handles file system boundaries. While WSL 2 can access Windows drives, direct manipulation of directories like
/mnt/c/Users/... inside a Linux container context can sometimes lead to inconsistencies if the parent directories are not explicitly created before the container initializes. Additionally, Docker runs as a Linux daemon within the WSL2 backend, meaning it respects Linux file permissions strictly. If the target directory on the host has ownership set to
root:root or restrictive modes that do not allow the
git user inside the Gitea container to write, the volume will effectively be "empty" or read-only in practice.
Creating the Directory Structure
Before running the compose command, you must ensure the host directories exist. Docker will create them if they are missing, but it creates them with
root ownership, which causes immediate permission conflicts for Gitea. To avoid this, create the directories manually in your WSL terminal using the following commands. Replace
<your-path> with your actual desired location, such as
~/gitea.
mkdir -p ~/gitea/data
mkdir -p ~/gitea/conf
mkdir -p ~/gitea/log
Next, assign ownership of these directories to the
git user. In most official Gitea images, the application runs as the user with UID 1000. You can verify this by checking the image documentation, but UID 1000 is the standard default.
chown -R 1000:1000 ~/gitea
This step is critical. Without setting the correct owner, the Gitea container will attempt to write to these folders, receive a "Permission denied" error, and fall back to an in-memory state or crash, leaving your host directory looking empty or unchanged.
Configuring docker-compose.yml
Your
docker-compose.yml should define the volumes clearly. A typical setup for Gitea involves mounting three specific paths. Ensure the syntax matches the format
host_path:container_path.
version: '3'
services:
gitea:
image: gitea/gitea:latest
container_name: gitea
restart: always
environment:
- USER_UID=1000
- USER_GID=1000
volumes:
- ./data:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "2222:22"
networks:
- gitea-net
networks:
gitea-net:
driver: bridge
Notice the use of relative paths (
./data) in the example above. When running Docker Compose, these paths are resolved relative to the location of the
docker-compose.yml file. If you are running this from WSL, ensure you are in the same directory when you execute
docker-compose up -d. If you prefer absolute paths, you can use the full WSL path, but relative paths are generally safer to avoid cross-filesystem permission issues.
For more details on managing Docker Compose installations and avoiding version mismatches, you might find our guide on
Resolving Version Mismatch During Docker Compose Installation on Debian helpful.
Verifying Permissions and Access
After starting the container, check if the data is being written correctly. Run the following command to inspect the logs for any permission-related warnings.
docker logs gitea
If you see messages about unable to create directories or write to
/data, re-check the
chown command you ran earlier. It is common to forget that Docker Compose might recreate volume directories if they were previously deleted or moved, resetting their ownership to root.
You can also test access directly from WSL by navigating to your data folder and creating a test file.
cd ~/gitea/data
touch testfile.txt
ls -l testfile.txt
If the file is owned by
root, the container cannot write to it. You must change the ownership again. If the file is owned by UID 1000, the container should be able to read and write without issue.
Troubleshooting Common Issues
Sometimes, even with correct permissions, the volume appears empty because the Gitea initialization process has not completed. Wait a few minutes after starting the container and check the web interface at
http://localhost:3000. If the UI loads but shows no repositories, the database might not have initialized properly. Restarting the container often forces a re-initialization if the data directory was corrupted or empty.
Another potential issue is SELinux contexts on some Linux distributions, though this is less common in standard WSL2 environments unless custom security modules are enabled. If you encounter strange behavior, try relabeling the volume with the
:z suffix in the compose file, although this is rarely needed in WSL.
For insights on optimizing your Docker environment in WSL to prevent resource bottlenecks, consider reading
Optimizing WSL Docker Image Sizes on Non-Admin PCs.
Frequently Asked Questions
Why does my Gitea container show no repositories after setup?
This usually indicates that the data volume is either not mounted correctly or lacks write permissions. Verify that the host directory is owned by UID 1000 and that the
docker-compose.yml paths match the actual directory structure.
Can I use a Windows path directly in Docker Compose?
While technically possible, it is not recommended due to performance overhead and permission complexities. It is better to store your Gitea data within the WSL2 filesystem (e.g.,
~/.local/share/gitea) and access it via the
\\wsl$\ network share if needed from Windows.
How do I backup my Gitea data?
Since you are using bind mounts, simply copying the contents of your host directory (e.g.,
~/gitea/data) provides a complete backup. Ensure the container is stopped during the copy process to prevent data corruption.
What happens if I delete the data directory?
Deleting the data directory will remove all repositories, users, and settings permanently. The next time the container starts, it will initialize a fresh instance, making previous data inaccessible unless you have a backup.
Is it safe to run Gitea on port 3000?
Yes, port 3000 is the default HTTP port for Gitea. However, ensure that no other local service is using this port. You can change the host port mapping in
docker-compose.yml to something else, like
3001:3000, if there is a conflict.