Need some advice to get started

Preamble / Hi I’m new to the forum/caddy

I’m trying to setup Caddy to host a few static websites on a small cloud server and I’m very excited about this project-it looks really great (cudos to the devs).

The docs seem to be very though, but “context” or “how to use/adapt/integrate the info” has been a challange. (Note to doc team, one or two “real life” examples for deploying a real server would really help.) I understand that Caddy can be configured with a jason API, but if I’m using a Caddyfile, I have been having difficulty translating JSON docs to use with a simple Caddyfile.

I was able to follow the "get started tutorials and do simple things locally, but when I had to put it together on a bare VPS in the cloud where security matters, and I need to get let’s encrypt work etc. I have really been struggling for several days.

My Use Case

I want to host a couple of static sites, and one or two small low traffic wordpress sites on a small cloud server.

QUESTION 1: Should I use a reverse proxy

Should I be using separate instances of Caddy – one for reverse proxy, and one or more instances to serve the site(s)? Given that my use case is simple and everything lives in one place is there any advantage to doing a reverse proxy over a single instance (security?)?

QUESTION 2:

Assuming these were real domains (with proper DNS, and the WordPress/php was correct, real email address) should this Caddyfile work or is there anything else required to have all the https:// work? Is setting up an account wiht Let’s Encrypt required, or do I need to add any special txt records to my DNS? I am having difficulty determining if I have a server setup problem or a “caddy” problem.

{
    email myemail@somedomain.com  
    acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}


example1.com {
	root * /www/example1.com
	file_server
}

example2.com {
	root * /www/example2.com
	file_server
}

example3.com {
	root * /www/example3.com
	file_server
}

examplewp1.com {
	root * /www/examplewp1.com
    # Whatever is needed for WordPress
    # Haven't figured that out yet.
	file_server
}

examplewp2.com {
	root * /www/examplewp2.com
    # Whatever is needed for WordPress
    # Haven't figured that out yet.
	file_server
}

#
#  If I wanted to add a reverse proxy for a microservice 
#  would it be OK to add for a simple use case like this?
#
example4.com {
	reverse_proxy localhost:9000
}

Thanks in advance for any advice/helpful feferences – sorry I couldn’t follow the prescribed format.

Welcome to Caddy!

We have this information all throughout our docs:

Hmm, why are you reading the JSON docs if you’re using the Caddyfile? If you’re using the Caddyfile, read the Caddyfile docs directly: The Caddyfile — Caddy Documentation ← we even have a WordPress example right on this page because it’s so common.

Use just one instance per machine (like with other web servers).

What do you mean by “reverse proxy over a single instance”? But the answer is probably “no”…

Why did you delete the help template? Your question is missing a lot of crucial details that are needed to help you. Please fill out the help template so you can get help. FYI our rules are here: FAQ - Caddy Community

Hi Matt, I am honoured that you would take the time to reply. As I said earlier I’m very excited about your project… All that functionality in a single binary WOW!

I can see the care and attention that has gone into the documentation, and I offer the following as suggestions as to what I would have found to get up and running quickly. Once I understand the context the documentation it is very complete and well written, but I have found discoverability an issue.

When you are an expert like yourself it’s easy to miss that many users (with basic administrator / decent power user skills) don’t know and don’t even know what they don’t know so they can construct a decent search query. I offer the following in the hope that it makes things easier for others and helps the adoption of the project.

We have this information all throughout our docs:

I originally found and followed this for Ubuntu, and it worked, but didn’t mention some important points -example “directories that need to be writable”. Some of this information is included in " * Keep Caddy Running — Caddy Documentation", but the only problem was without your forum post I didn’t find it–and even worse I wasted time because I didn’t know to look for it.

Including information about the setup, like what user the server is running as (caddy), the linux service, the location of the caddy file (/etc/caddy/Caddyfile) and how to do a lot of the things described in “Getting Started” ( Getting Started — Caddy Documentation ) that can no longer be used when using the linux service. I can’t just do caddy run, and see a stream of output on the terminal, and I don’t know how to get it.

I’m reading JSON because that is what is on the getting started page, and the search engine often put me on JSON examples when I searched for answers to my questions.

I didn’t think the WordPress example was complete - I haven’t set up WordPress for a few years, and the last time was on Apache. As I recall there were URL rewrites and .htaccess to hide directories no longer work. Which php package(s) would that work with. Again just looking at a terminal log of a sample case would answer so many questions/give a hint as to what questions need to be answered.

It’s a common problem with open source projects getting the pieces to fit together because there isn’t documentation overlap. I understand that it’s not your responsibility to fully document WordPress stuff, but this type of material is easy to find for Apache/Nginx. If your “Quick Start” had a full install for (1) A static site (2) Multiple static sites (3) WordPress (and maybe NodeJS or whatever else you think is popular). Once this material gets out, the YouTubers will make tutorials.

It would also be very helpful if the quick start mentioned/reference the let’s encrypt “test setup” (so I ddin’t get my domain banned by let’s encrypt), and a simple statement the as long as ports 80/443 are open everything should work / no need to register an account (or am I wrong about this)?

I read the rules, and at this point I was look for “general help” / and an overview of how I should be setting thiings up. I tried a lot of stuff and to document it would have created a massive TLDR; post that likely would not have given me the answers I needed. (And I do agree that to solve a specific issue on a real functioning system your template is the way to go.)

I will say that I may be forced to do it, but I am not really very comfortable having a real domain name and server configuration files freely available in a public forum for crackers to scrape. If there is an obvious security flaw it’s flagging it for the world to see – no need to search – just “exploit here”. Depending on the issue full information may not be necessary, but I know where you are coming from – little seemingly inconsequential things can make all the difference (as I have described in my post.)

I really like where you are going with Caddy, and I hope this feedback is useful to you The TLDR; is the “Quck Start” needs some work (and can easily leverage all the excellent documentation that has been written so far).

Thanks for all your excellent work and sorry this post was so long.

My Question that I still need an answer to

Is the “example” Caddy file that I included in my initial post conceptually sound. If those were working domains/web App on Port 9000 would that be a decent way to set things up?

Thanks for the thoughtful feedback @zzz.

Ah yeah, that’s understandable. We do expect people to know how to use their computers. So if you are administering a Linux system, you should know how to run programs in the command line, and if running as a service, that you know how to do that as well. It’s outside the scope of the Caddy documentation to teach users how to Linux. But we do show you how to use Caddy on Linux; you just have to know Linux.

Are you using Google? That usually surfaces Caddyfile docs for me. Either way, though, that sounds like an unfortunate output from the search engines. Maybe filing a request with the search engine would be the best way to go there, as we don’t have control over what they show.

It’s literally that simple. Of course, we expect that you know how to set up PHP and the database and use your computer, etc. (and that’s outside the scope of our documentation).

I think what you’re looking for would be a great addition to our underutilized community wiki which we link to prominently from our docs sidebar and the forum at the top of all pages. We hear a lot of people asking for end-to-end, step-by-step tutorials, but nobody is willing to go to the effort of contributing them to our wiki. :frowning: It would be awesome if you wanted to contribute! A lot of users like yourself would read those and benefit.

There are thousands of ways to use a web server, and we don’t favor any one in particular, at least not officially in our docs. But again, these are great candidates for our community wiki. We just need people to contribute!

Which quick start are you referring to? The only one that employs public certificates is the HTTPS quick start, which does say this already, very explicitly at the top:

In this tutorial, replace example.com with your actual domain name.

Set your domain’s A/AAAA records point to your server. You can do this by logging into your DNS provider and managing your domain name.

Before continuing, verify correct records with an authoritative lookup. Replace example.com with your domain name, and if you are using IPv6 replace type=A with type=AAAA:

curl "https://cloudflare-dns.com/dns-query?name=example.com&type=A" \
  -H "accept: application/dns-json"

Also make sure your server is externally reachable on ports 80 and 443 from a public interface.

If you’re on your home or other restricted network, you may need to forward ports or adjust firewall settings.

To clarify, I brought it up because while the help template can be ignored when asking something that isn’t about Caddy, your question actually was about Caddy. You were asking for troubleshooting help regarding your Caddy config, which is precisely what the help template is for…

I understand, but there is no security benefit of withholding your domains from a public page. DNS records are public, scanning the entire Internet takes only a few minutes, and all publicly-trusted certificates are recorded into public CT logs. So trying to hide that information from a random forum is only going to frustrate those who are trying to help you.

We do offer private help for sponsors and business customers if you are interested in that though!

Yes. But I would do it this way:

{
    email myemail@somedomain.com  
    acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}

example1.com, example2.com, example3.com {
	root * /www/{host}
	file_server
}

examplewp1.com, examplewp2.com {
	root * /www/{host}
    # Whatever is needed for WordPress
    # Haven't figured that out yet.
	file_server
}

example4.com {
	reverse_proxy localhost:9000
}

Much simpler.

2 Likes

Thanks very much Matt!

No argument there… I don’t expect the Caddy documentation to explain systemctl - there is a ton of well written material on systemctl that is easy to find.

I just went back and noticed that I overlooked:
]Installing this package automatically starts and runs Caddy as a systemd service named caddy, and also comes with a caddy-api service which is not enabled by default, should you need it.

From what I can see there several people struggling with Let’s Encrypt/Docker because there is fundamental things that are not explicit in the documentation or that have been omitted from the setup. People don’t know to look for them or what they should be looking for. For example what paths need to be made persistent in a docker volume or need to be writable on the server. I suspect in my case that the install / first run of caddy did not create all the necessary paths.

I’m not here to complain, I’m happy to help if you will help me.

I need to lab some caddy setups so that I can make decisions about What I want to set up/how I want to set it up. So I’m going to be starting again from scratch and document everything for myself.

If you will help me by answering some questions (or getting a knowledgeable friend/associate to help), I am happy to post all my work in the forum. And of course by doing it in public maybe the community will pitch in as well. Then hopefully I or someone else can go back an make good knowledge base articles.

I have registered a few “free-domains” and I plan to throw up a server on oracle cloud Free Tier so that it won’t have any personal or privacy implications.

If you (or someone else) can entertain some questions that might be a bit beyond the normal scope and/or go a bit deeper with your answer as to what to look out for/got-yas/security implications, I will do my best to thoroughly document my work.

I was thinking about calling the post “CADDY LAB” or something like that. What do you think?

If you want me to go ahead what section of the forum do you want me to post in and what do you want to call the post?

The docs on Docker Hub explain in full. There’s also a docker-compose example here:

Sure – just make the post in the Help category (as you did here), that’s the right place for it.

Thanks for that input… I will go back and look at those again.

The challenge that I am having (and if I am correctly interpreting why some (maybe even many) of the questions are appearing in the forum is that people are missing key points because the material is scattered over different locations, or gets missed because it isn’t needed for several steps down the process.

Let me be very clear Matt’s documentation is excellent!

I’m trying to create something that integrates the information in the order that it is needed.

Take my current situation, I am attempting to set up caddy in a cloud environment that I am not familiar with. I need to create a procedure for going step-by-step to install, and then check the installation in a quick an efficient manner. Are the necessary ports open? Did the install process create all the needed working directories and do they have the correct permissions?

For someone who is a generalist or just getting started having a few hints on how to troubleshot step-by-step should save a ton of time. I personally like to build/break/fix/tear down a couple of times so that I get the feel of how a software system works, and I for me (and I suspect ofthers) a detailed outline would help.

Sure. What other questions do you have? (Maybe open a new topic, this one has gotten quite deep into other territory.)

Thanks Matt… I’ll set up another post in HELP. A couple of quick questions for this thread:

  1. ABOUT THE FORUM: Can I go back and edit the first post in a thread that has been open for awhile? What is the maximum post length? (If it’s short I should reserve a couple of posts at the beginning of the thread).
    My plan is to put a refactored version in the first post so that it isn’t necessary to read though the entire thread, but still have all the backup available in case someone wants it.

  2. What data directories should exist immediately after installing caddy as per your instructions ( Install — Caddy Documentation )?
    I see
    Data directory ( Conventions — Caddy Documentation )
    $HOME/.local/share/caddy
    Configuration Directory ( Conventions — Caddy Documentation )
    $HOME/.config/caddy
    What about http://server.com/.well-known/acme-challenge/QX....oO that is requested by Let’s Encrypt? Is there a real path/file stored somewhere, or are these virtual paths that Caddy handles internally?

  3. What is the best way to test that caddy is serving properly over port 443 without having a domain attached. (possibly using curl) The goal is to make sure that there are no server/firewall issues before worrying about DNS/Let’s Encrypt.
    .
    Can I turn off TLS and do curl ( http://ipaddress:443 )?
    Is the command ( auto_https off ) in the global section? Can this be applied to a single site?
    – or –
    Would it be better to create a self signed cert?
    Will the command ( tls internal ) placed in the global section provide https with caddy’s own self-signed?
    Can give Caddy a key / cert to use for it to do the signing with?

Yep, I believe so.

I think it’s 99k characters. It’s a lot, so don’t worry about reserving posts or w/e.

You don’t need to create any, the installation should automate it already.

Nope, they aren’t served from file, they’re served from memory. State is written to disk, but those paths are not directly web accessible.

You can turn on the local_certs global option, which will make Caddy issue all certs with its built-in local CA; these certs won’t be trusted by browsers unless you installed the root CA cert in your system’s trust store.

The local_certs global option is essentially a shortcut for putting tls internal in all sites.

That’s a bad idea; port 443 should only ever be used for HTTPS.

It’s a global option, yes. If you want to turn off HTTPS for a site, then prefix it with http://.

Caddy can do this for you (not exactly self-signed, but rather signed by a self-managed CA… but effectively the same thing).

You can’t put tls internal in global options; tls is a site directive. You can use the local_certs global option though.

Yes, you can specify your own cert/key pair with the tls directive:

@ francislavoie Merci beaucoup pour la réponse rapide!

That’s what I expected, but permission issues messed this up the first time I tried. I was on a ubuntu server using 1001(ubuntu), and unfortunatly I was expecting things to “just work”, so I wasn’t keeping notes. I belive it was the data directory (not sure) that wasn’t created. I created the directory manually and chown’d it to the caddy user and I got a little closer to a working system.

I agree in a production environment. In my environment I have multiple firewalls to worry about, and I want a quick and easy way to make sure that they all have the appropriate ports open.

So does this replace the automatic RootCA that Caddy would normally use? Will Caddy still generate intermediate certs signed by the user provided CA?

There is so much https going around that I’m thinking that having a common root CA for all my devices, using it to sign intermediate Certs and putting the root in the trust stores of my browsers.

Why do you hate me?

For each good tutorial on YouTube, there are 100x more that are plain disrespect of my time. And a few that are actually dangerous. Not to mention outdated ones.

2 Likes

I don’t hate you… I agree there is a lot of junk, and I have also learned a lot from Youtube. Tom Lawrence does some excellent videos on pfSense Firewall and TrueNAS server (and many other things) just to name one. I found his stuff very useful. I have also seen demos of software that tell me if I want to know more about it.

Publication date will often make sure the info is current, and it is a simple matter to skip into the video to check the presentation quality. If it’s crap, go find something else.

I guarantee it will be worth what you pay for it :slight_smile: (At least as long as you doesn’t push you over your monthly bandwidth cap!)

I know and appreciate the YouTubers I follow.

When I go on YouTube following a Google search, that’s a whole another story.

1 Like

I have found that using the YouTube search is a useful starting point, but it does require some selectivity. The thumbnail and description often show if there has been some effort put it, and a minute of watching (or less) will tell if it’s worth watching.

In fact that’s how I found out about Caddy… someone did a video where they mentioned Caddy and did a very simple tutorial … just the Hello World over port 80. Not great, but it got me to look up the web site and get excited about the potential of Caddy… Learned how to use Docker, KVM/Virt Manager, got a good overview of the various Linux distros, and a lot of security news. … and I’ve had to click off a lot of crap as well, so I get your point.

Cheers.

If you’re running with user 1001 then it sounds like you didn’t run Caddy as a systemd service, which is what the installation methods set up for you.

Either way, the storage locations are documented here:

And the defaults under $HOME should always already be writable by the current user… because it’s the user’s own $HOME.

Point is, if it didn’t just work then it’s probably cause you did something weird or atypical.

I think we’re talking about the same thing. Caddy’s self-managed CA is both the root and intermediate; the root signs the intermediate, and the intermediate signs the leaf certs. The root has a 10 year lifetime by default, intermediates have a 7 day lifetime, and leaf certs have a 12 hour lifetime.

+1 - I agree