mac-media-stack-advanced is an advanced media server designed specifically for macOS. It helps you organize and stream your movies, TV shows, and music. The server manages media files automatically. It fixes issues, converts files for smooth playback, and keeps data safe with backups. You get quality profiles and metadata handled without manual work. The system also monitors downloads and uses VPN failover to keep your connection secure.
This project uses popular tools behind the scenes, like Tdarr for file transcoding, Recyclarr for quality control, and Kometa for metadata. It includes automation for media downloads and backup routines. You do not need to understand coding or programming to use it.
- Auto-healing: Fixes problems in your media files automatically.
- Transcoding: Converts videos to formats that work on your devices using Tdarr.
- Quality Profiles: Ensures media meets your quality standards with Recyclarr.
- Metadata Automation: Downloads artwork, descriptions, and episode info using Kometa.
- Download Watchdog: Keeps track of new downloads and imports them correctly.
- VPN Failover: Switches to backup VPN if the main one fails.
- Automated Backups: Saves your settings and data regularly.
- Self-hosted: You keep full control by running everything on your own macOS machine.
- Integrates with apps: Works with Jellyfin, Plex, Sonarr, Radarr, Lidarr, and Tidarr.
To run mac-media-stack-advanced on your Mac, make sure your system meets these requirements:
- macOS version: 11.0 (Big Sur) or later
- At least 8 GB of RAM (16 GB recommended for larger libraries)
- Minimum 50 GB free disk space (more depending on media size)
- Stable internet connection
- Docker and Docker Compose installed
- Admin access to install software and run Docker containers
If you use VPN failover, your VPN client should support WireGuard or OpenVPN protocols.
Follow these steps to download and run mac-media-stack-advanced on your Mac.
Visit the release page to get the latest version:
- This page contains all stable versions and update notes.
- Download the asset for macOS or any files labeled for your system.
- Save the files to a folder you can easily access.
mac-media-stack-advanced runs all services inside Docker containers:
-
Download and install Docker Desktop for Mac.
-
Follow the installer steps.
-
After installation, open Terminal and run:
docker --version docker-compose --version -
These commands confirm Docker is ready.
- Extract the downloaded release archive.
- You should see files like
docker-compose.ymland folders for configuration. - Open the folder in Finder or use Terminal.
Some settings need to match your home environment:
- Open the
.envor configuration files in a text editor. - Set your media paths for Movies, TV Shows, Music, and Downloads.
- Configure network options, including VPN if you use one.
- Adjust quality profiles as needed.
- Save changes.
If you don’t want to change anything, default settings are ready to use.
Open Terminal and navigate to the folder with docker-compose.yml. Then run:
docker-compose up -d
- This command starts all containers in the background.
- Services will start initializing; this may take a few minutes.
- You can check logs with:
docker-compose logs -f
Once running, you can open your media server in a web browser:
- Jellyfin (for streaming):
http://localhost:8096 - Kometa (for metadata):
http://localhost:4200 - Tdarr (for transcoding):
http://localhost:8265 - Recyclarr (for quality profiles):
http://localhost:7878
Use the default user names and passwords provided in the documentation folder if prompted.
To update mac-media-stack-advanced:
- Download the new release files.
- Replace old files with new ones.
- Run the following commands:
docker-compose pull
docker-compose up -d
- This updates existing containers with the new versions.
- If containers do not start, check Docker is running and your system meets requirements.
- Confirm ports 8096, 4200, 8265, and 7878 are free.
- If media files don’t show up, check your media folder paths are correct.
- Restart Docker Desktop if you experience connection issues.
- Monitor disk space regularly to avoid service interruption.
- Backups run automatically, but you can manually copy your config folder to an external drive.
After extraction, you will see:
docker-compose.yml— main service configurationconfig/— settings and user data stored heremedia/— place your movies, TV shows, and music herelogs/— system logs for troubleshooting.env— environment variables for config options
You can always find the latest version here:
Click the blue button and select the macOS release file to download and start the installation.
mac-media-stack-advanced uses Docker to run multiple services:
- Jellyfin streams your media to all devices.
- Tdarr converts videos into formats that work best for your devices.
- Recyclarr ensures media files meet your quality rules.
- Kometa grabs cover art, descriptions, and episode info.
- Sonarr, Radarr, and Lidarr automate TV shows, movies, and music downloads.
- WireGuard VPN keeps your connection protected, switching automatically if one VPN drops.
- Automated backups make sure your data stays safe.
All services talk to each other using Docker networks. You can manage and monitor each service via web portals.
Use these in the Terminal inside the project folder:
-
Start:
docker-compose up -d -
Stop:
docker-compose down -
View logs:
docker-compose logs -f -
Update containers:
docker-compose pull docker-compose up -d
You can find detailed guides and configuration help in the repository wiki. Look for:
- How to set up quality profiles
- Advanced transcoding options
- VPN failover configuration
- Backup management
Use the Issues tab on GitHub to report bugs or request help from the community.