📦 Git LFS Server (Dockerized 🐳)

GitHub LFS Storage Feels Expensive? Self-Host Your Own Git LFS Server! A Complete Dockerized Git LFS Server Setup with git-lfs/lfs-test-server and tus/tusd

Features

• ✅ Git LFS Test Server: Full-featured Git LFS server for testing and development (can be used on production too)
• ✅ Tusd Integration: Resumable upload support via the tus protocol
• ✅ Admin Web UI: Built-in management interface
• ✅ Persistent Storage: Docker volumes for LFS content and metadata
• ✅ One File Configuration: All settings via .env file

Quick Start

1. Clone the Repository

git clone https://github.com/neosubhamoy/git-lfs-server-dockerized.git
cd git-lfs-server-dockerized

2. Create Environment File

cp .env.example .env

Edit .env to customize your configuration (optional - defaults work out of the box, for more info read the .env.example file).

3. Build and Run

Before running build, Make sure you have docker and docker-compose-plugin installed in your host machine.

# Build the Docker image
docker compose build

# Start the services
docker compose up -d

# View logs (If you want to :)
docker compose logs -f lfs-server

4. Access the Services

• LFS API Endpoint: http://localhost:8080
• WebAdmin UI (If Admin Exists): http://localhost:8080/mgmt

Usage with Git LFS

Before using, Make sure you have git and git-lfs plugin installed in your machine.

Fresh Start (for non-lfs repo)

1. Initialize Git LFS in your repository:

git lfs install

2. Configure the LFS endpoint:

git config -f .lfsconfig lfs.url http://localhost:8080

3. Track files with LFS:

git lfs track "*.zip"  # Tracks all .zip files

4. Add and commit:

git add .gitattributes
git add your-large-file.zip
git commit -m "Add large lfs file"
git push

Migration (for existing lfs repo)

1. Configure the LFS endpoint:

git config -f .lfsconfig lfs.url http://localhost:8080

2. Add and commit:

git commit -m "Changed lfs server"
git push

3. Add new lfs server as remote (temporarily, for migration):

git remote add lfs-new http://localhost:8080

4. Push all lfs objects to new server:

git lfs push --all lfs-new

Now, You can delete the temporarily added remote (as it's no longer needed) by running: git remote remove lfs-new

Nginx Reverse Proxy Setup Notes

-------------   <-----   -----------   ----->  -------------
| 👱 Client |   HTTPS   | ⚙️ Nginx |   HTTP   | 📦 Server |
-------------   ----->   -----------   <-----  -------------

   Git LFS  <-->  lfs.yourdomain.com  <-->  localhost:8080

1. Add these lines in your nginx config under server block:

client_max_body_size 0;           # Unlimited max file upload size
client_body_timeout 300s;         # 5 minutes timeout for slow uploads
client_body_buffer_size 128k;     # Optimal Initial buffer size

2. Disable https on container environment settings (in .env file):

PROTOCOL=http   # As, You will most probably serve HTTPS (SSL/TLS) via Nginx. So, enabling HTTPS on container doesn't make sense (Also, sometimes could create potential problems, just leave it http)

3. Set proper host name on container environment settings (in .env file):

LFS_HOST=lfs.yourdomain.com  # This should match the exact host (domain name) from where the actual LFS server will be accessed finnally. Also, You will set this in your .lfsconfig file later (This, variable is also used to generate the LFS file upload URLs)

4. Also, don't use cloudflare proxy on top of your nginx proxy. As that could potentialy break the LFS API due to it's max upload filesize restrictions. Set it to: DNS Only

Other Useful Docker Commands

# Stop services
docker compose down

# List running services
docker compose ps

# Restart services
docker compose restart

# Rebuild after changes
docker compose build --no-cache

# Remove all data (WARNING: deletes volumes)
docker compose down -v

Volumes and Backup

Data is persisted in the following directories (volumes):

./data/
├── lfs-content/      # LFS object files
├── lfs-meta/         # lfs.db SQLite database
└── lfs_tusserver/    # Temporary tusd uploads

Backup Strategy:

• Regularly backup ./data/lfs-meta/lfs.db (metadata database)
• Backup ./data/lfs-content/ (actual LFS objects)
• The ./data/lfs_tusserver/ directory contains temporary files and can be excluded

License

This Docker setup is provided under the MIT LICENSE.

The bundled projects have their own licenses:

• lfs-test-server: MIT License
• tusd: MIT License

References

• Git LFS
• lfs-test-server
• tusd
• tus Protocol

Support

For issues related to:

• This Docker setup: Open an issue in this repository
• lfs-test-server: Visit git-lfs/lfs-test-server
• tusd: Visit tus/tusd

---

An Open Sourced Project - Developed with ❤️ by Subhamoy