https://github.com/mac9sb/configuration
Root configuration for developer tooling, sites and services on macOS
https://github.com/mac9sb/configuration
Last synced: 4 months ago
JSON representation
Root configuration for developer tooling, sites and services on macOS
- Host: GitHub
- URL: https://github.com/mac9sb/configuration
- Owner: mac9sb
- Created: 2026-02-08T01:39:34.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-02-20T13:52:07.000Z (5 months ago)
- Last Synced: 2026-02-20T17:56:45.891Z (5 months ago)
- Language: TypeScript
- Homepage:
- Size: 278 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Server
Personal macOS development environment — manages sites, tooling, and infrastructure as a single repository with git submodules.
## Todo
asdfasdf
- [ ] Look into creating cron jobs where codex will analyze repo and submodules for clean up tasks and create PR's
## Structure
```
~/Developer/
├── setup.sh # Main setup script
├── uninstall.sh # Teardown script
├── .env.example # R2 credentials template (tracked)
├── .env.local # R2 credentials (gitignored)
├── utilities/
│ ├── dotfiles/ # Symlinked to ~/.*
│ └── githooks/ # Installed to .git/hooks/ during setup
├── tooling/
│ ├── orchestrator/
│ │ └── Sources/OrchestratorCLI/Resources/
│ │ ├── cloudflared/ # Tunnel + primary domain config template
│ │ ├── launchd/ # Launchd plist templates
│ │ ├── newsyslog/ # Log rotation config template
│ │ └── scripts/ # Runtime scripts
│ └── / # CLI tool submodules
└── sites/ # Website submodules
```
## Quick Start
```sh
git clone --recursive https://github.com/mac9sb/server.git ~/Developer
cd ~/Developer
cp .env.example .env.local # fill in R2 credentials
./setup.sh # prompts for sudo during Phase A
```
> [!NOTE]
> Setup uses the repo `Brewfile` (Homebrew + mas) to install tools, casks, and App Store apps.
> Sign into the App Store first if you want MAS installs to succeed.
## Architecture
```
Internet → Cloudflare Tunnel (maclong) → Apache :80 → VirtualHost routing
│
┌─────────────────────────────┼──────────────────────────────┐
│ │ │
maclong.dev api.maclong.dev cool-app.com
(VirtualHost → (VirtualHost → (VirtualHost →
static from proxy → :8001) proxy → :8002)
.output)
localhost/site-name/ ← path-based dev access for all
```
- **Primary domain**: set in `tooling/orchestrator/Sources/OrchestratorCLI/Resources/cloudflared/config.yml` via `# primary-domain: maclong.dev`
- **Domain sites**: directory name contains a dot → custom domain VirtualHost (e.g. `sites/cool-app.com/`)
- **Subdomain sites**: directory name has no dot → subdomain of primary domain (e.g. `sites/api/` → `api.maclong.dev`)
- **Local dev**: every site is also accessible at `http://localhost/site-name/` via path-based routing
- **Static sites**: `.output/` directory → Apache serves via `DocumentRoot` or `Alias`
- **Server apps**: `.build/release/Application` (or `.build//release/Application`) → reverse-proxied via `mod_proxy`
- **State**: single SQLite dasdfasdfatabase (WAL mode) at `~/Library/Application Support/com.mac9sb/state.db`
## Submodules
Submodules are the source of truth for what repos exist; orchestrator derives Apache and cloudflared routing directly from the filesystem. Adding or removing a submodule is all you need to do for routing — custom domains still require a DNS route to the tunnel (see below).
### Adding
```sh
cd ~/Developer
# Primary domain site (directory name = domain)
git submodule add https://github.com/mac9sb/portfolio.git sites/maclong.dev
# Subdomain site (no dot → becomes api.maclong.dev)
git submodule add https://github.com/mac9sb/api.git sites/api
# Custom domain site (dot in name → becomes cool-app.com)
git submodule add https://github.com/mac9sb/cool-app.git sites/cool-app.com
# Tooling
git submodule add https://github.com/mac9sb/.git tooling/
git commit -m "Add suasdfsadfbmodule"
```
The orchestrator daemon auto-detects new sites and configures Apache + process supervision.
### Updating
```sh
git submodule update --remote --merge
git add sites/
git commit -m "Update submodule"
```
> [!WARNING]
> **Do NOT use `git -C sites/ pull`** — this bypasses submodule tracking. The pre-push hook will block inconsistent pushes.
## Domain Routing
Apache routing is derived entirely from site directory names and the primary domain configured in `tooling/orchestrator/Sources/OrchestratorCLI/Resources/cloudflared/config.yml` (ingress entries are auto-managed by orchestrator):
```
# primary-domain: maclong.dev
```
| Directory name | VirtualHost `ServerName` | How it works |
|---|---|---|
| `sites/maclong.dev/` | `maclong.dev` | Dot in name → custom domain (also the primary) |
| `sites/api/` | `api.maclong.dev` | No dot → subdomain of primary domain |
| `sites/cool-app.com/` | `cool-app.com` | Dot in name → custom domain |
Every site also gets a path-based entry in the default VirtualHost for local development at `http://localhost/site-name/`.
### Adding a Subdomain Site
Subdomain DNS is already covered by the `*.maclong.dev` wildcard — just add the submodule:
```sh
git submodule add https://github.com/mac9sb/api.git sites/api
git commit -m "Add api submodule"
# → automatically served at api.maclong.dev
```
### Adding a Custom Domain Site
Custom domains need a DNS route to the tunnel; the cloudflared ingress entry is auto-managed:
1. Add the submodule (directory name = the domain):
```sh
git submodule add https://github.com/mac9sb/cool-app.git sites/cool-app.com
```
2. Orchestrator automatically updates `tooling/orchestrator/Sources/OrchestratorCLI/Resources/cloudflared/config.yml` (no manual edits needed).
3. Route DNS to the tunnel:
```sh
cloudflared tunnel route dns maclong cool-app.com
```
4. Orchestrator picks up the change, regenerating Apache config and ingress entries automatically.
### Renaming / Changing Domains
```sh
git mv sites/old-name sites/new-name.com
git commit -m "Move to new-name.com"
```
## Cloudflare Tunnel
The tunnel config at `tooling/orchestrator/Sources/OrchestratorCLI/Resources/cloudflared/config.yml` is version-controlled (no credentials) and rendered to `~/.cloudflared/config.yml` during setup. It contains:
- The **primary domain** as a parseable comment (`# primary-domain: maclong.dev`)
- **Ingress rules** for the primary domain and all discovered site hostnames
- All ingress rules forward to Apache on `:80` — Apache handles per-site routing via VirtualHosts
See the comments in `tooling/orchestrator/Sources/OrchestratorCLI/Resources/cloudflared/config.yml` for full details.
### First-Time Setup
```sh
sudo ./setup.sh # renders config, installs agents
cloudflared tunnel login
cloudflared tunnel create maclong --credentials-file ~/.cloudflared/maclong.json
cloudflared tunnel route dns maclong maclong.dev
cloudflared tunnel route dns maclong "*.maclong.dev"
```
### With Existing Tunnel
If the tunnel already exists (e.g., created on another machine or a previous install), fetch the credentials and add DNS routes:
```sh
# Authenticate with Cloudflare (creates ~/.cloudflared/cert.pem)
cloudflared tunnel login
# Fetch credentials for the existing tunnel
cloudflared tunnel token --cred-file ~/.cloudflared/maclong.json maclong
# Add DNS routes (creates CNAME records pointing to the tunnel)
cloudflared tunnel route dns maclong maclong.dev
cloudflared tunnel route dns maclong "*.maclong.dev"
# Use -f / --overwrite-dns to replace existing DNS records
cloudflared tunnel route dns -f maclong "*.maclong.dev"
```
## Daily Backups
A daily backup script runs at 03:00 via launchd, snapshots all SQLite databases, packages them into tarballs, and uploads to Cloudflare R2 using pure `curl` + S3v4 signing (no AWS CLI needed). Local backups are retained for 7 days.
See `tooling/orchestrator/Sources/OrchestratorCLI/Resources/scripts/backup.sh` for the full process. Copy `.env.example` to `.env.local` and fill in your R2 credentials:
```sh
cp .env.example .env.local
```
## Useful Commands
```sh
# Apache
sudo apachectl configtest && sudo apachectl restart
# Launchd agents
launchctl list | grep mac9sb
# Restart a specific server
orchestrator restart
# Logs
tail -f ~/Library/Logs/com.mac9sb/.log
tail -f ~/Library/Logs/com.mac9sb/orchestrator-*.log
tail -f /var/log/apache2/sites/-error.log
# Submodules
git submodule status
git submodule update --remote --merge
# Manual backup
~/Developer/tooling/orchestrator/Sources/OrchestratorCLI/Resources/scripts/backup.sh
# Rebuild a site
cd ~/Developer/sites/ && swift build -c release
# Tunnel
cloudflared tunnel info maclong
cloudflared tunnel list
```
## Teardown
```sh
sudo ./uninstall.sh # standard (preserves CLI tools, SSH keys, credentials)
sudo ./uninstall.sh --all # full (also removes cloudflared)
```
See `uninstall.sh` for exactly what gets removed and what's preserved.