Skip to content

Commit 38f9c28

Browse files
liamvibecodesliamvibecodes
committed
Initial release: permission auditor for macOS Docker media stacks
0 parents  commit 38f9c28

8 files changed

Lines changed: 584 additions & 0 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug-report.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
name: Bug Report
2+
description: Something isn't working
3+
labels: ["bug"]
4+
body:
5+
- type: textarea
6+
id: description
7+
attributes:
8+
label: What happened?
9+
description: Describe the bug
10+
validations:
11+
required: true
12+
- type: textarea
13+
id: expected
14+
attributes:
15+
label: What did you expect?
16+
validations:
17+
required: true
18+
- type: input
19+
id: macos-version
20+
attributes:
21+
label: macOS version
22+
placeholder: e.g. Sonoma 14.2
23+
validations:
24+
required: true
25+
- type: input
26+
id: chip
27+
attributes:
28+
label: Mac chip
29+
placeholder: e.g. M1, M2 Pro, M4
30+
validations:
31+
required: true
32+
- type: textarea
33+
id: logs
34+
attributes:
35+
label: Relevant logs
36+
description: Paste any error output or logs
37+
render: shell
38+
validations:
39+
required: false

‎.github/ISSUE_TEMPLATE/feature-request.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
name: Feature Request
2+
description: Suggest a new feature or improvement
3+
labels: ["enhancement"]
4+
body:
5+
- type: textarea
6+
id: description
7+
attributes:
8+
label: What would you like?
9+
description: Describe the feature
10+
validations:
11+
required: true
12+
- type: textarea
13+
id: why
14+
attributes:
15+
label: Why?
16+
description: What problem does this solve?
17+
validations:
18+
required: false

‎.github/workflows/validate.yml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
name: Validate
2+
3+
on:
4+
push:
5+
pull_request:
6+
7+
jobs:
8+
validate:
9+
runs-on: ubuntu-latest
10+
steps:
11+
- name: Checkout
12+
uses: actions/checkout@v4
13+
14+
- name: Validate shell scripts
15+
run: |
16+
bash -n fix-permissions.sh

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
.env
2+
config/
3+
logs/

‎CONTRIBUTING.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Contributing
2+
3+
Thanks for your interest in contributing to Mac Media Stack Permissions.
4+
5+
## How to Help
6+
7+
- **Bug reports**: Open an issue with your macOS version, Docker version, and the script output.
8+
- **Feature requests**: Open an issue describing what you'd like and why.
9+
- **Pull requests**: Fork the repo, make your changes on a branch, and open a PR. Keep changes focused on one thing.
10+
11+
## Guidelines
12+
13+
- Test your changes on a clean macOS install if possible.
14+
- Don't commit `.env` files, API keys, or any credentials.
15+
- Keep scripts compatible with both Intel and Apple Silicon Macs.
16+
- Match the existing code style (bash scripts use `set -e`, consistent formatting).
17+
18+
## Questions?
19+
20+
Open an issue. There are no dumb questions.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 liamvibecodes
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
<div align="center">
2+
<br>
3+
<a href="#quick-start">
4+
<img src="https://img.shields.io/badge/MAC_MEDIA_STACK_PERMISSIONS-00C853?style=for-the-badge&logo=apple&logoColor=white" alt="Mac Media Stack Permissions" height="40" />
5+
</a>
6+
<br><br>
7+
<strong>Audit and fix file permissions across your *arr Docker stack on macOS</strong>
8+
<br>
9+
<sub>Permissions are the #1 headache with Docker media stacks on macOS.<br>This tool finds and fixes permission issues before they break your setup.</sub>
10+
<br><br>
11+
<img src="https://img.shields.io/badge/Docker-2496ED?style=flat-square&logo=docker&logoColor=white" />
12+
<img src="https://img.shields.io/badge/OrbStack-000000?style=flat-square&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48Y2lyY2xlIGN4PSIxMiIgY3k9IjEyIiByPSIxMCIgZmlsbD0id2hpdGUiLz48L3N2Zz4=&logoColor=white" />
13+
<img src="https://img.shields.io/badge/macOS-000000?style=flat-square&logo=apple&logoColor=white" />
14+
<img src="https://img.shields.io/badge/Bash-4EAA25?style=flat-square&logo=gnubash&logoColor=white" />
15+
<br><br>
16+
<img src="https://img.shields.io/github/stars/liamvibecodes/mac-media-stack-permissions?style=flat-square&color=yellow" />
17+
<img src="https://img.shields.io/github/license/liamvibecodes/mac-media-stack-permissions?style=flat-square" />
18+
<br><br>
19+
</div>
20+
21+
## The Problem
22+
23+
File permissions are the most common issue with Docker media stacks on macOS. Every other post on r/selfhosted and r/radarr is someone debugging why Sonarr can't write to their download folder or Radarr can't move files after import.
24+
25+
The usual causes:
26+
- PUID/PGID set differently across containers
27+
- Volume mounts owned by root instead of your user
28+
- macOS privacy controls blocking Docker's disk access
29+
- .env file missing or has stale user IDs
30+
31+
This script audits everything in one pass and tells you exactly what's wrong.
32+
33+
## What It Checks
34+
35+
| Check | What It Looks For |
36+
|-------|------------------|
37+
| **Runtime detection** | OrbStack or Docker Desktop installed and running |
38+
| **PUID/PGID consistency** | All containers using the same user/group IDs |
39+
| **.env validation** | PUID/PGID set and matching your current user |
40+
| **Volume permissions** | Host directories owned by the expected user |
41+
| **Full Disk Access** | Docker/OrbStack has macOS disk access permissions |
42+
| **Compose config** | docker-compose.yml exists and is parseable |
43+
44+
## Quick Start
45+
46+
```bash
47+
git clone https://github.com/liamvibecodes/mac-media-stack-permissions.git
48+
cd mac-media-stack-permissions
49+
bash fix-permissions.sh
50+
```
51+
52+
Or run directly:
53+
54+
```bash
55+
curl -fsSL https://raw.githubusercontent.com/liamvibecodes/mac-media-stack-permissions/main/fix-permissions.sh | bash
56+
```
57+
58+
## Usage
59+
60+
```bash
61+
# Audit only (default, no changes made)
62+
bash fix-permissions.sh
63+
64+
# Audit a custom media directory
65+
bash fix-permissions.sh --path /Volumes/Media
66+
67+
# Fix all permission issues
68+
bash fix-permissions.sh --fix
69+
70+
# Fix with custom path
71+
bash fix-permissions.sh --fix --path /Volumes/Media
72+
```
73+
74+
## Example Output
75+
76+
```
77+
==============================
78+
Permission Audit
79+
==============================
80+
81+
OK Runtime: OrbStack detected
82+
OK docker-compose.yml found at /Users/you/Media/docker-compose.yml
83+
OK .env PUID (501) matches current user
84+
OK .env PGID (20) matches current group
85+
WARN PUID mismatch: sonarr uses 1000, expected 501
86+
OK config/ owned by you (501:20)
87+
FAIL downloads/ owned by root (0:0), expected 501:20
88+
WARN Full Disk Access not confirmed for OrbStack
89+
90+
==============================
91+
Summary: 4 passed, 2 warnings, 1 failed
92+
==============================
93+
```
94+
95+
## Fix Mode
96+
97+
Run with `--fix` to automatically resolve permission issues:
98+
99+
- Runs `chown -R` on directories with wrong ownership
100+
- Reports what was changed
101+
102+
The script never modifies docker-compose.yml or .env. It only fixes file ownership on disk.
103+
104+
## Works With
105+
106+
- [mac-media-stack](https://github.com/liamvibecodes/mac-media-stack) — One-command Plex + Sonarr + Radarr setup
107+
- [mac-media-stack-advanced](https://github.com/liamvibecodes/mac-media-stack-advanced) — Power-user setup with transcoding, quality profiles, and automation
108+
109+
## Author
110+
111+
Built by [@liamvibecodes](https://github.com/liamvibecodes)
112+
113+
## License
114+
115+
[MIT](LICENSE)

0 commit comments

Comments
 (0)