Charon/README.md

Caddy Proxy Manager+ (CPMP)

Make your websites easy to reach! 🚀

This app helps you manage multiple websites and apps from one simple dashboard. Think of it like a traffic director for your internet services - it makes sure people get to the right place when they visit your websites.

No coding required! Just point, click, and you're done. ✨

---

🤔 What Does This Do?

Simple Explanation: Imagine you have 5 different apps running on different computers in your house. Instead of remembering 5 complicated addresses, you can use one simple address like myapps.com, and this tool figures out where to send people based on what they're looking for.

Real-World Example:

• Someone types: blog.mysite.com → Goes to your blog server
• Someone types: shop.mysite.com → Goes to your online shop server
• All managed from one beautiful dashboard!

---

✨ What Can It Do?

• 🎨 Beautiful Dark Interface - Easy on the eyes, works on phones and computers
• 🔄 Manage Multiple Websites - Add, edit, or remove websites with a few clicks
• 🖥️ Connect Different Servers - Works with servers anywhere (your closet, the cloud, anywhere!)
• 📥 Import Old Settings - Already using Caddy? Bring your old setup right in
• 🔍 Test Before You Save - Check if servers are reachable before going live
• 💾 Saves Everything Safely - Your settings are stored securely
• 🔐 Secure Your Sites - Add that green lock icon (HTTPS) to your websites
• 🌐 Works with Live Updates - Perfect for chat apps and real-time features

---

📋 Quick Links

• 🏠 Start Here - Your first setup in 5 minutes
• 📚 All Documentation - Find everything you need
• 📥 Import Guide - Bring in your existing setup
• 🐛 Report Problems - We'll help!

---

🚀 The Super Easy Way to Start

Want to skip all the technical stuff? Use Docker! (It's like a magic app installer)

Step 1: Get Docker

Don't have Docker? Download it here - it's free!

Step 2: Run One Command

Open your terminal and paste this:

# Clone the repository
git clone https://github.com/Wikid82/CaddyProxyManagerPlus.git
cd CaddyProxyManagerPlus

# Start the stack
docker-compose up -d

Step 3: Open Your Browser

Go to: http://localhost:8080

That's it! 🎉 You're ready to start adding your websites!

💡 Tip: Not sure what a terminal is? On Windows, search for "Command Prompt". On Mac, search for "Terminal".

For more details, check out the Docker Deployment Guide.

🔌 Connecting to Remote Servers (Optional)

Want to see containers on OTHER servers?

If you have apps running on a different computer (like a Raspberry Pi or a VPS) and want CPMP to see them automatically:

1. Copy the docker-compose.remote.yml file to that other computer.
2. Run it there: docker compose -f docker-compose.remote.yml up -d
3. Connect in CPMP:
   • Go to "Add Proxy Host"
   • Click "Remote Docker?"
   • Type the address: tcp://<IP-OF-OTHER-COMPUTER>:2375

⚠️ IMPORTANT SECURITY WARNING: Think of this like leaving your front door unlocked. ONLY do this if your computers are connected via a secure VPN (like Tailscale or WireGuard) or are on a private home network that strangers can't access. Never do this on a public server without a VPN!

---

🛠️ The Developer Way (If You Like Code)

Want to tinker with the app or help make it better? Here's how:

-### What You Need First:

• Go 1.24+ - Get it here (the "engine" that runs the app)
• Node.js 20+ - Get it here (helps build the pretty interface)

Getting It Running:

1. Download the app

git clone https://github.com/Wikid82/CaddyProxyManagerPlus.git
cd CaddyProxyManagerPlus

2. Start the "brain" (backend)

cd backend
go mod download           # Gets the tools it needs
go run ./cmd/seed/main.go # Adds example data
go run ./cmd/api/main.go  # Starts the engine

3. Start the "face" (frontend) - Open a NEW terminal window

cd frontend
npm install     # Gets the tools it needs
npm run dev     # Shows you the interface

4. See it work!
   • Main app: http://localhost:3001
   • Backend: http://localhost:8080

Quick Docker Way (Developers Too!)

docker-compose up -d

Opens at http://localhost:3001

---

🏗️ How It's Built (For Curious Minds)

Don't worry if these words sound fancy - you don't need to know them to use the app!

The "Backend" (The Smart Part)

• Go - A fast programming language (like the app's brain)
• Gin - Helps handle web requests quickly
• SQLite - A tiny database (like a filing cabinet for your settings)

The "Frontend" (The Pretty Part)

• React - Makes the buttons and forms look nice
• TypeScript - Keeps the code organized
• TailwindCSS - Makes everything pretty with dark mode

Where Things Live

CaddyProxyManagerPlus/
├── backend/          ← The "brain" (handles your requests)
│   ├── cmd/          ← Starter programs
│   ├── internal/     ← The actual code
│   └── data/         ← Where your settings are saved
├── frontend/         ← The "face" (what you see and click)
│   ├── src/          ← The code for buttons and pages
│   └── coverage/     ← Test results (proves it works!)
└── docs/             ← Help guides (including this one!)

---

⚙️ Making Changes to the App (For Developers)

Want to add your own features or fix bugs? Here's how to work on the code:

Working on the Backend (The Brain)

1. Get the tools it needs

cd backend
go mod download

2. Set up the database (adds example data to play with)

go run ./cmd/seed/main.go

3. Make sure it works (runs tests)

go test ./... -v

4. Start it up

go run ./cmd/api/main.go

Now the backend is running at http://localhost:8080

Working on the Frontend (The Face)

1. Get the tools it needs

cd frontend
npm install

2. Make sure it works (runs tests)

npm test              # Keeps checking as you code
npm run test:ui       # Pretty visual test results
npm run test:coverage # Shows what's tested

3. Start it up

npm run dev

Now the frontend is running at http://localhost:3001

Custom Settings (Optional)

Want to change ports or locations? Create these files:

Backend Settings (backend/.env):

PORT=8080                    # Where the backend listens
DATABASE_PATH=./data/cpm.db  # Where to save data
LOG_LEVEL=debug              # How much detail to show

Frontend Settings (frontend/.env):

VITE_API_URL=http://localhost:8080  # Where to find the backend

---

📡 Controlling the App with Code (For Developers)

Want to automate things or build your own tools? The app has an API (a way for programs to talk to it).

What's an API? Think of it like a robot that can do things for you. You send it commands, and it does the work!

Things the API Can Do:

Check if it's alive

GET /api/v1/health

Like saying "Hey, are you there?"

Manage Your Websites

GET    /api/v1/proxy-hosts          # Show me all websites
POST   /api/v1/proxy-hosts          # Add a new website
GET    /api/v1/proxy-hosts/:uuid    # Show me one website
PUT    /api/v1/proxy-hosts/:uuid    # Change a website
DELETE /api/v1/proxy-hosts/:uuid    # Remove a website

Manage Your Servers

GET    /api/v1/remote-servers          # Show me all servers
POST   /api/v1/remote-servers          # Add a new server
GET    /api/v1/remote-servers/:uuid    # Show me one server
PUT    /api/v1/remote-servers/:uuid    # Change a server
DELETE /api/v1/remote-servers/:uuid    # Remove a server
POST   /api/v1/remote-servers/:uuid/test # Is this server reachable?

Import Old Files

GET    /api/v1/import/status          # How's the import going?
GET    /api/v1/import/preview         # Show me what will import
POST   /api/v1/import/upload          # Start importing a file
POST   /api/v1/import/commit          # Finish the import
DELETE /api/v1/import/cancel          # Cancel the import

Want more details and examples? Check out the complete API guide!

---

🧪 Making Sure It Works (Testing)

What's testing? It's like double-checking your homework. We run automatic checks to make sure everything works before releasing updates!

Checking the Backend

cd backend
go test ./... -v                    # Check everything
go test ./internal/api/handlers/... # Just check specific parts
go test -cover ./...                # Check and show what's covered

Results: ✅ 6 tests passing (all working!)

Checking the Frontend

cd frontend
npm test                  # Keep checking as you work
npm run test:coverage     # Show me what's tested
npm run test:ui          # Pretty visual results

Results: ✅ 24 tests passing (~70% of code checked)

• Layout: 100% ✅ (fully tested)
• Import Table: 90% ✅ (almost fully tested)
• Forms: ~60% ✅ (mostly tested)

What does this mean for you? The app is reliable! We've tested it thoroughly so you don't have to worry.

---

🗄️ Where Your Settings Are Saved

What's a database? Think of it as a super organized filing cabinet where the app remembers all your settings!

The app saves:

• Your Websites - All the sites you've set up
• Your Servers - The computers you've connected
• Your Caddy Files - Original configuration files (if you imported any)
• Security Stuff - SSL certificates and who can access what
• App Settings - Your preferences and customizations
• Import History - What you've imported and when

Want the technical details? Check out the database guide.

Good news: It's all saved in one tiny file, and you can back it up easily!

---

📥 Bringing In Your Old Caddy Files

Already using Caddy and have configuration files? No problem! You can import them:

Super Simple Steps:

1. Click "Import" in the app
2. Upload your file (or just paste the text)
3. Look at what it found - the app shows you what it understood
4. Fix any conflicts - if something already exists, choose what to do
5. Click "Import" - done!

It's drag-and-drop easy! The app figures out what everything means.

Need help? Read the step-by-step import guide with pictures and examples!

---

🔗 Helpful Links

• 📋 What We're Working On: https://github.com/users/Wikid82/projects/7
• 🐛 Found a Problem?: https://github.com/Wikid82/CaddyProxyManagerPlus/issues
• 💬 Questions?: https://github.com/Wikid82/CaddyProxyManagerPlus/discussions

---

🤝 Want to Help Make This Better?

We'd love your help! Whether you can code or not, you can contribute:

Ways You Can Help:

• 🐛 Report bugs (things that don't work)
• 💡 Suggest new features (ideas for improvements)
• 📝 Improve documentation (make guides clearer)
• 🔧 Fix issues (if you know how to code)
• ⭐ Star the project (shows you like it!)

If You Want to Add Code:

1. Make your own copy (click "Fork" on GitHub)
2. Make your changes in a new branch
3. Test your changes to make sure nothing breaks
4. Send us your changes (create a "Pull Request")

Don't worry if you're new! We'll help you through the process. Check out our Contributing Guide for details.

---

📄 Legal Stuff (License)

This project is free to use! It's under the MIT License, which basically means:

• ✅ You can use it for free
• ✅ You can change it
• ✅ You can use it for your business
• ✅ You can share it

See the LICENSE file for the formal details.

---

🙏 Special Thanks

• Inspired by Nginx Proxy Manager (similar tool, different approach)
• Built with Caddy Server (the power behind the scenes)
• Made beautiful with TailwindCSS (the styling magic)

---

💬 Questions?

Stuck? Don't be shy!

• 📖 Check the documentation
• 💬 Ask in Discussions
• 🐛 Open an Issue if something's broken

We're here to help! Everyone was a beginner once. 🌟

---

Version 0.1.0
Built with ❤️ by @Wikid82
Made for humans, not just techies!