Files

CI ce8a51e6c7 fix(workflows): replace invalid semantic-version action with fallback script

2025-11-29 02:49:21 +00:00

8.1 KiB

Raw Permalink Blame History

🏠 Getting Started with Charon

Welcome! This guide will walk you through setting up your first proxy. Don't worry if you're new to this - we'll explain everything step by step!

🤔 What Is This App?

Think of this app as a traffic controller for your websites and apps.

Here's a simple analogy: Imagine you have several houses (websites/apps) on different streets (servers). Instead of giving people complicated directions to each house, you have one main address (your domain) where a helpful guide (the proxy) sends visitors to the right house automatically.

What you can do:

✅ Make multiple websites accessible through one domain
✅ Route traffic from example.com to different servers
✅ Manage SSL certificates (the lock icon in browsers)
✅ Control who can access what

📋 Before You Start

You'll need:

A computer (Windows, Mac, or Linux)
Docker installed (it's like a magic box that runs apps)
- Don't have it? Get Docker here
5 minutes of your time

That's it! No programming needed.

Step 1: Get the App Running

The Easy Way (Recommended)

Open your terminal (or Command Prompt on Windows) and paste this:

docker run -d \
   -p 8080:8080 \
   -v caddy_data:/app/data \
   --name charon \
   ghcr.io/wikid82/charon:latest

What does this do? It downloads and starts the app. You don't need to understand the details - just copy and paste!

Check If It's Working

Open your web browser
Go to: http://localhost:8080
You should see the app! 🎉

Didn't work? Check if Docker is running. On Windows/Mac, look for the Docker icon in your taskbar.

🎯 Step 2: Create Your First Proxy Host

Let's set up your first proxy! We'll create a simple example.

What's a Proxy Host?

A Proxy Host is like a forwarding address. When someone visits mysite.com, it secretly sends them to 192.168.1.100:3000 without them knowing.

Let's Create One!

Click "Proxy Hosts" in the left sidebar
Click "+ Add Proxy Host" button (top right)
Fill in the form:

📝 Domain Name: (What people type in their browser)
```
myapp.local
```
This is like your house's street address

📍 Forward To: (Where the traffic goes)
```
192.168.1.100
```
This is where your actual app is running

🔢 Port: (Which door to use)
```
3000
```
Apps listen on specific "doors" (ports) - 3000 is common for web apps

🌐 Scheme: (How to talk to it)
```
http
```
Choose http for most apps, https if your app already has SSL
Click "Save"

Congratulations! 🎉 You just created your first proxy! Now when you visit http://myapp.local, it will show your app from 192.168.1.100:3000.

🌍 Step 3: Set Up a Remote Server (Optional)

Sometimes your apps are on different computers (servers). Let's add one!

What's a Remote Server?

Think of it as telling the app about other computers you have. Once added, you can easily send traffic to them.

Adding a Remote Server

Click "Remote Servers" in the left sidebar
Click "+ Add Server" button
Fill in the details:

🏷️ Name: (A friendly name)
```
My Home Server
```
🌐 Hostname: (The address of your server)
```
192.168.1.50
```
📝 Description: (Optional - helps you remember)
```
The server in my office running Docker
```
Click "Test Connection" - this checks if the app can reach your server
Click "Save"

Now when creating proxy hosts, you can pick this server from a dropdown instead of typing the address every time!

📥 Step 4: Import Existing Caddy Files (If You Have Them)

Already using Caddy and have configuration files? You can bring them in!

What's a Caddyfile?

It's a text file that tells Caddy how to route traffic. If you're not sure if you have one, you probably don't need this step.

How to Import

Click "Import Caddy Config" in the left sidebar
Choose your method:
- Drag & Drop: Just drag your Caddyfile into the box
- Paste: Copy the contents and paste them in the text area
Click "Parse Config" - the app reads your file
Review the results:
- ✅ Green items = imported successfully
- ⚠️ Yellow items = need your attention (conflicts)
- ❌ Red items = couldn't import (will show why)
Resolve any conflicts (the app will guide you)
Click "Import Selected"

Done! Your existing setup is now in the app.

Need more help? Check the detailed Import Guide

💡 Tips for New Users

1. Start Small

Don't try to import everything at once. Start with one proxy host, make sure it works, then add more.

2. Use Test Connection

When adding remote servers, always click "Test Connection" to make sure the app can reach them.

3. Check Your Ports

Make sure the ports you use aren't already taken by other apps. Common ports:

80 - Web traffic (HTTP)
443 - Secure web traffic (HTTPS)
3000-3999 - Apps often use these
8080-8090 - Alternative web ports

4. Local Testing First

Test everything with local addresses (like localhost or 192.168.x.x) before using real domain names.

5. Save Backups

The app stores everything in a database. The Docker command above saves it in caddy_data - don't delete this!

⚙️ Environment Variables (Advanced)

Want to customize how the app runs? You can set these options:

Common Options

Variable	Default	What It Does
`CHARON_ENV`	`development`	Set to `production` for live use (CHARON_ preferred; CPM_ still supported)
`CHARON_HTTP_PORT`	`8080`	Change the web interface port
`CHARON_ACME_STAGING`	`false`	Use Let's Encrypt staging (see below)

🧪 Development Mode: ACME Staging

Problem: Testing SSL certificates repeatedly can hit Let's Encrypt rate limits (50 certs/week)

Solution: Use staging mode for development!

docker run -d \
  -p 8080:8080 \
   -e CHARON_ACME_STAGING=true \
  -v caddy_data:/app/data \
  --name caddy-proxy-manager \
   ghcr.io/wikid82/charon:latest

What happens:

✅ No rate limits
⚠️ Certificates are "fake" (untrusted by browsers)
Perfect for testing

For production: Remove CHARON_ACME_STAGING or set to false (CPM_ vars still supported)

📖 Learn more: ACME Staging Guide

🐛 Something Not Working?

App Won't Start

Check if Docker is running - look for the Docker icon
Check if port 8080 is free - another app might be using it
Try: docker ps to see if it's running

Can't Access the Website

Check your spelling - domain names are picky
Check the port - make sure the app is actually running on that port
Check the firewall - might be blocking connections

Import Failed

Check your Caddyfile syntax - paste it at Caddy Validate
Look at the error message - it usually tells you what's wrong
Start with a simple file - test with just one site first

Hit Let's Encrypt Rate Limit

Use staging mode - set CHARON_ACME_STAGING=true (see above; CHARON_ preferred; CPM_ still supported)
Wait a week - limits reset weekly
Check current limits - visit Let's Encrypt Status

📚 What's Next?

You now know the basics! Here's what to explore:

🔐 Add SSL Certificates - get the green lock icon
🚦 Set Up Access Lists - control who can visit your sites
⚙️ Configure Settings - customize the app
🔌 Try the API - control everything with code

🆘 Still Need Help?

We're here for you!

You're doing great! 🌟
Remember: Everyone was a beginner once. Take your time and have fun!

8.1 KiB Raw Permalink Blame History