itsi 0.2.26 → 0.2.27

data/crates/itsi_server/src/server/binds/tls.rs

@@ -1,8 +1,9 @@
 use base64::{engine::general_purpose, Engine as _};
-use itsi_acme::{AcmeAcceptor, AcmeConfig, AcmeState};
+use itsi_acme::{AcmeAcceptor, AcmeConfig, AcmeState, Http01Handler, ResolvesServerCertAcme};
 use itsi_error::Result;
-use itsi_tracing::info;
+use itsi_tracing::{error, info};
 use locked_dir_cache::LockedDirCache;
+use parking_lot::{Mutex as ParkingMutex, RwLock as ParkingRwLock};
 use rcgen::ExtendedKeyUsagePurpose;
 use rcgen::{
     BasicConstraints, CertificateParams, DistinguishedName, DnType, IsCa, KeyPair, KeyUsagePurpose,
@@ -17,9 +18,14 @@ use std::{
     collections::HashMap,
     fs,
     io::{BufReader, Error},
-    sync::Arc,
+    sync::{
+        atomic::{AtomicBool, Ordering},
+        Arc,
+    },
+    thread::JoinHandle,
 };
-use tokio::sync::Mutex;
+use tokio::runtime::Builder as RuntimeBuilder;
+use tokio::sync::{mpsc, watch};
 use tokio_rustls::{rustls::ServerConfig, TlsAcceptor};
 
 use crate::env::{
@@ -29,14 +35,300 @@ use crate::env::{
 
 mod locked_dir_cache;
 
+#[derive(Debug, Clone)]
+pub struct ManagedTlsDomainStatus {
+    pub domain: String,
+    pub status: String,
+    pub last_error: Option<String>,
+}
+
+#[derive(Clone)]
+struct DynamicAcmeConfigTemplate {
+    client_config: Arc<ClientConfig>,
+    directory_url: String,
+    contact: Vec<String>,
+    cache_dir: String,
+}
+
+impl DynamicAcmeConfigTemplate {
+    fn state_for_domain(
+        &self,
+        domain: &str,
+        resolver: Arc<ResolvesServerCertAcme>,
+        http01_handler: Arc<Http01Handler>,
+        http01_enabled: bool,
+    ) -> AcmeState<Error> {
+        let state = AcmeConfig::new([domain])
+            .contact(self.contact.clone())
+            .cache(LockedDirCache::new(self.cache_dir.clone()))
+            .directory(&self.directory_url)
+            .client_tls_config(self.client_config.clone());
+        let mut state = AcmeState::new_with_resolver(
+            state,
+            resolver,
+            http01_handler,
+            Some(domain.to_string()),
+        );
+        state.set_http01_enabled(http01_enabled);
+        state
+    }
+}
+
+enum DynamicAcmeCommand {
+    Register(String),
+    Unregister(String),
+    Shutdown,
+}
+
+#[derive(Clone)]
+pub struct DynamicAcmeManager {
+    inner: Arc<DynamicAcmeManagerInner>,
+}
+
+struct DynamicAcmeManagerInner {
+    resolver: Arc<ResolvesServerCertAcme>,
+    http01_registry: Arc<ParkingRwLock<HashMap<String, Arc<Http01Handler>>>>,
+    statuses: Arc<ParkingRwLock<HashMap<String, ManagedTlsDomainStatus>>>,
+    http01_enabled: Arc<AtomicBool>,
+    initialized: AtomicBool,
+    initial_domains: Vec<String>,
+    command_tx: mpsc::UnboundedSender<DynamicAcmeCommand>,
+    thread_handle: ParkingMutex<Option<JoinHandle<()>>>,
+}
+
+impl DynamicAcmeManager {
+    fn new(template: DynamicAcmeConfigTemplate, initial_domains: Vec<String>) -> Self {
+        let resolver = ResolvesServerCertAcme::new();
+        let http01_handler = Arc::new(Http01Handler::new());
+        let http01_registry = Arc::new(ParkingRwLock::new(HashMap::new()));
+        let statuses = Arc::new(ParkingRwLock::new(HashMap::new()));
+        let http01_enabled = Arc::new(AtomicBool::new(false));
+        let (command_tx, mut command_rx) = mpsc::unbounded_channel();
+
+        let resolver_clone = resolver.clone();
+        let http01_handler_clone = http01_handler.clone();
+        let http01_registry_clone = http01_registry.clone();
+        let statuses_clone = statuses.clone();
+        let http01_enabled_clone = http01_enabled.clone();
+
+        let thread_handle = std::thread::spawn(move || {
+            let runtime = RuntimeBuilder::new_current_thread()
+                .enable_all()
+                .build()
+                .expect("Failed to build dynamic ACME runtime");
+            runtime.block_on(async move {
+                let mut cancellations: HashMap<String, watch::Sender<bool>> = HashMap::new();
+
+                while let Some(command) = command_rx.recv().await {
+                    match command {
+                        DynamicAcmeCommand::Register(domain) => {
+                            let domain = domain.to_ascii_lowercase();
+                            if cancellations.contains_key(&domain) {
+                                continue;
+                            }
+
+                            statuses_clone.write().insert(
+                                domain.clone(),
+                                ManagedTlsDomainStatus {
+                                    domain: domain.clone(),
+                                    status: "pending".to_string(),
+                                    last_error: None,
+                                },
+                            );
+                            http01_registry_clone
+                                .write()
+                                .insert(domain.clone(), http01_handler_clone.clone());
+
+                            let (cancel_tx, mut cancel_rx) = watch::channel(false);
+                            cancellations.insert(domain.clone(), cancel_tx);
+
+                            let resolver = resolver_clone.clone();
+                            let http01_handler = http01_handler_clone.clone();
+                            let registry = http01_registry_clone.clone();
+                            let statuses = statuses_clone.clone();
+                            let template = template.clone();
+                            let enabled = http01_enabled_clone.clone();
+                            let task_domain = domain.clone();
+
+                            tokio::spawn(async move {
+                                statuses.write().insert(
+                                    task_domain.clone(),
+                                    ManagedTlsDomainStatus {
+                                        domain: task_domain.clone(),
+                                        status: "issuing".to_string(),
+                                        last_error: None,
+                                    },
+                                );
+                                let mut state = template.state_for_domain(
+                                    &task_domain,
+                                    resolver.clone(),
+                                    http01_handler,
+                                    enabled.load(Ordering::SeqCst),
+                                );
+
+                                loop {
+                                    tokio::select! {
+                                        changed = cancel_rx.changed() => {
+                                            if changed.is_ok() && *cancel_rx.borrow() {
+                                                resolver.remove_auth_key(&task_domain);
+                                                resolver.remove_cert_for_domain(&task_domain);
+                                                registry.write().remove(&task_domain);
+                                                statuses.write().remove(&task_domain);
+                                                break;
+                                            }
+                                        }
+                                        event = futures::StreamExt::next(&mut state) => {
+                                            match event {
+                                                Some(Ok(_)) => {
+                                                    let mut statuses = statuses.write();
+                                                    if let Some(status) = statuses.get_mut(&task_domain) {
+                                                        status.status = "active".to_string();
+                                                        status.last_error = None;
+                                                    }
+                                                }
+                                                Some(Err(err)) => {
+                                                    let mut statuses = statuses.write();
+                                                    if let Some(status) = statuses.get_mut(&task_domain) {
+                                                        status.status = "failed".to_string();
+                                                        status.last_error = Some(err.to_string());
+                                                    }
+                                                }
+                                                None => break,
+                                            }
+                                        }
+                                    }
+                                }
+                            });
+                        }
+                        DynamicAcmeCommand::Unregister(domain) => {
+                            let domain = domain.to_ascii_lowercase();
+                            if let Some(cancel_tx) = cancellations.remove(&domain) {
+                                let _ = cancel_tx.send(true);
+                            } else {
+                                http01_registry_clone.write().remove(&domain);
+                                resolver_clone.remove_auth_key(&domain);
+                                resolver_clone.remove_cert_for_domain(&domain);
+                                statuses_clone.write().remove(&domain);
+                            }
+                        }
+                        DynamicAcmeCommand::Shutdown => {
+                            for (_, cancel_tx) in cancellations.drain() {
+                                let _ = cancel_tx.send(true);
+                            }
+                            break;
+                        }
+                    }
+                }
+            });
+        });
+
+        Self {
+            inner: Arc::new(DynamicAcmeManagerInner {
+                resolver,
+                http01_registry,
+                statuses,
+                http01_enabled,
+                initialized: AtomicBool::new(false),
+                initial_domains,
+                command_tx,
+                thread_handle: ParkingMutex::new(Some(thread_handle)),
+            }),
+        }
+    }
+
+    pub fn resolver(&self) -> Arc<ResolvesServerCertAcme> {
+        self.inner.resolver.clone()
+    }
+
+    pub fn set_http01_enabled(&self, enabled: bool) {
+        self.inner.http01_enabled.store(enabled, Ordering::SeqCst);
+    }
+
+    pub fn initialize_domains(&self) {
+        if self.inner.initialized.swap(true, Ordering::SeqCst) {
+            return;
+        }
+
+        for domain in &self.inner.initial_domains {
+            self.register_domain(domain.clone());
+        }
+    }
+
+    pub fn register_domain(&self, domain: String) {
+        let _ = self
+            .inner
+            .command_tx
+            .send(DynamicAcmeCommand::Register(domain));
+    }
+
+    pub fn unregister_domain(&self, domain: &str) {
+        let _ = self
+            .inner
+            .command_tx
+            .send(DynamicAcmeCommand::Unregister(domain.to_string()));
+    }
+
+    pub fn http01_response(&self, host: &str, path: &str) -> Option<String> {
+        self.inner
+            .http01_registry
+            .read()
+            .get(host)
+            .and_then(|handler| handler.handle_challenge_request(path))
+    }
+
+    pub fn statuses(&self) -> Vec<ManagedTlsDomainStatus> {
+        let mut statuses = self
+            .inner
+            .statuses
+            .read()
+            .values()
+            .cloned()
+            .collect::<Vec<_>>();
+        statuses.sort_by(|a, b| a.domain.cmp(&b.domain));
+        statuses
+    }
+}
+
+impl Drop for DynamicAcmeManagerInner {
+    fn drop(&mut self) {
+        let _ = self.command_tx.send(DynamicAcmeCommand::Shutdown);
+        if let Some(handle) = self.thread_handle.lock().take() {
+            if let Err(err) = handle.join() {
+                error!("Dynamic ACME manager thread join failed: {:?}", err);
+            }
+        }
+    }
+}
+
 #[derive(Clone)]
 pub enum ItsiTlsAcceptor {
     Manual(TlsAcceptor),
-    Automatic(
-        AcmeAcceptor,
-        Arc<Mutex<AcmeState<Error>>>,
-        Arc<ServerConfig>,
-    ),
+    Automatic {
+        acme_acceptor: AcmeAcceptor,
+        manager: DynamicAcmeManager,
+        server_config: Arc<ServerConfig>,
+    },
+}
+
+impl ItsiTlsAcceptor {
+    pub fn manager(&self) -> Option<DynamicAcmeManager> {
+        match self {
+            ItsiTlsAcceptor::Automatic { manager, .. } => Some(manager.clone()),
+            ItsiTlsAcceptor::Manual(_) => None,
+        }
+    }
+
+    pub fn set_http01_enabled(&self, enabled: bool) {
+        if let ItsiTlsAcceptor::Automatic { manager, .. } = self {
+            manager.set_http01_enabled(enabled);
+        }
+    }
+
+    pub fn initialize_domains(&self) {
+        if let ItsiTlsAcceptor::Automatic { manager, .. } = self {
+            manager.initialize_domains();
+        }
+    }
 }
 
 /// Generates a TLS configuration based on either :
@@ -52,66 +344,79 @@ pub fn configure_tls(
     let domains = query_params
         .get("domains")
         .map(|v| v.split(',').map(String::from).collect::<Vec<_>>())
-        .or_else(|| query_params.get("domain").map(|v| vec![v.to_string()]));
+        .or_else(|| query_params.get("domain").map(|v| vec![v.to_string()]))
+        .unwrap_or_default();
 
     if query_params.get("cert").is_some_and(|c| c == "acme") {
-        if let Some(domains) = domains {
-            let directory_url = &*ITSI_ACME_DIRECTORY_URL;
-            info!(
-                domains = format!("{:?}", domains),
-                directory_url, "Requesting acme cert"
-            );
-            let acme_contact_email = query_params
-                .get("acme_email")
-                .map(|s| s.to_string())
-                .or_else(|| (*ITSI_ACME_CONTACT_EMAIL).as_ref().ok().map(|s| s.to_string()))
-                .ok_or_else(|| itsi_error::ItsiError::ArgumentError(
-                    "acme_email query param or ITSI_ACME_CONTACT_EMAIL must be set before you can auto-generate let's encrypt certificates".to_string(),
-                ))?;
-
-            let acme_config = AcmeConfig::new(domains)
-                .contact([format!("mailto:{}", acme_contact_email)])
-                .cache(LockedDirCache::new(&*ITSI_ACME_CACHE_DIR))
-                .directory(directory_url);
-
-            let acme_state = if let Ok(ca_pem_path) = &*ITSI_ACME_CA_PEM_PATH {
-                let mut root_cert_store = RootCertStore::empty();
-
-                let ca_pem = fs::read(ca_pem_path).expect("failed to read CA pem file");
-                let mut ca_reader = BufReader::new(&ca_pem[..]);
-                let der_certs: Vec<CertificateDer> = certs(&mut ca_reader)
-                    .collect::<std::result::Result<Vec<CertificateDer>, _>>()
-                    .map_err(|e| {
-                        itsi_error::ItsiError::ArgumentError(format!(
-                            "Invalid ACME CA Pem path {:?}",
-                            e
-                        ))
-                    })?;
-                root_cert_store.add_parsable_certificates(der_certs);
-
-                let client_config = ClientConfig::builder()
+        let directory_url = &*ITSI_ACME_DIRECTORY_URL;
+        info!(
+            domains = format!("{:?}", domains),
+            directory_url, "Requesting acme cert"
+        );
+        let acme_contact_email = query_params
+            .get("acme_email")
+            .map(|s| s.to_string())
+            .or_else(|| (*ITSI_ACME_CONTACT_EMAIL).as_ref().ok().map(|s| s.to_string()))
+            .ok_or_else(|| itsi_error::ItsiError::ArgumentError(
+                "acme_email query param or ITSI_ACME_CONTACT_EMAIL must be set before you can auto-generate let's encrypt certificates".to_string(),
+            ))?;
+
+        let client_config = if let Ok(ca_pem_path) = &*ITSI_ACME_CA_PEM_PATH {
+            let mut root_cert_store = RootCertStore::empty();
+
+            let ca_pem = fs::read(ca_pem_path).expect("failed to read CA pem file");
+            let mut ca_reader = BufReader::new(&ca_pem[..]);
+            let der_certs: Vec<CertificateDer> = certs(&mut ca_reader)
+                .collect::<std::result::Result<Vec<CertificateDer>, _>>()
+                .map_err(|e| {
+                    itsi_error::ItsiError::ArgumentError(format!("Invalid ACME CA Pem path {:?}", e))
+                })?;
+            root_cert_store.add_parsable_certificates(der_certs);
+
+            Arc::new(
+                ClientConfig::builder()
                     .with_root_certificates(root_cert_store)
-                    .with_no_client_auth();
-                acme_config
-                    .client_tls_config(Arc::new(client_config))
-                    .state()
-            } else {
-                acme_config.state()
-            };
-
-            let mut rustls_config = ServerConfig::builder()
-                .with_no_client_auth()
-                .with_cert_resolver(acme_state.resolver());
-
-            rustls_config.alpn_protocols = vec![b"h2".to_vec(), b"http/1.1".to_vec()];
-
-            let acceptor = acme_state.acceptor();
-            return Ok(ItsiTlsAcceptor::Automatic(
-                acceptor,
-                Arc::new(Mutex::new(acme_state)),
-                Arc::new(rustls_config),
-            ));
-        }
+                    .with_no_client_auth(),
+            )
+        } else {
+            let mut root_store = RootCertStore::empty();
+            root_store.extend(
+                webpki_roots::TLS_SERVER_ROOTS
+                    .iter()
+                    .map(|ta| rustls::pki_types::TrustAnchor {
+                        subject: ta.subject.clone(),
+                        subject_public_key_info: ta.subject_public_key_info.clone(),
+                        name_constraints: ta.name_constraints.clone(),
+                    }),
+            );
+            Arc::new(
+                ClientConfig::builder()
+                    .with_root_certificates(root_store)
+                    .with_no_client_auth(),
+            )
+        };
+
+        let manager = DynamicAcmeManager::new(
+            DynamicAcmeConfigTemplate {
+                client_config,
+                directory_url: directory_url.to_string(),
+                contact: vec![format!("mailto:{}", acme_contact_email)],
+                cache_dir: ITSI_ACME_CACHE_DIR.to_string(),
+            },
+            domains.clone(),
+        );
+
+        let mut rustls_config = ServerConfig::builder()
+            .with_no_client_auth()
+            .with_cert_resolver(manager.resolver());
+
+        rustls_config.alpn_protocols = vec![b"h2".to_vec(), b"http/1.1".to_vec()];
+
+        return Ok(ItsiTlsAcceptor::Automatic {
+            acme_acceptor: AcmeAcceptor::new(manager.resolver()),
+            manager,
+            server_config: Arc::new(rustls_config),
+        });
     }
     let (certs, key) = if let (Some(cert_path), Some(key_path)) =
         (query_params.get("cert"), query_params.get("key"))
@@ -121,7 +426,7 @@ pub fn configure_tls(
         let key = load_private_key(key_path);
         (certs, key)
     } else {
-        generate_ca_signed_cert(domains.unwrap_or(vec![host.to_owned()]))?
+        generate_ca_signed_cert(if domains.is_empty() { vec![host.to_owned()] } else { domains })?
     };
 
     let mut config = ServerConfig::builder()

data/crates/itsi_server/src/server/signal.rs

@@ -63,7 +63,7 @@ pub fn send_lifecycle_event(event: LifecycleEvent) {
     }
 }
 
-fn receive_signal(signum: i32, _: sighandler_t) {
+extern "C" fn receive_signal(signum: i32) {
     debug!("Received signal: {}", signum);
     SIGINT_COUNT.fetch_add(-1, Ordering::SeqCst);
     let event = match signum {
@@ -96,20 +96,25 @@ fn receive_signal(signum: i32, _: sighandler_t) {
     }
 }
 
+fn signal_handler() -> sighandler_t {
+    receive_signal as *const () as sighandler_t
+}
+
 pub fn reset_signal_handlers() -> bool {
     debug!("Resetting signal handlers");
     SIGINT_COUNT.store(0, Ordering::SeqCst);
     SHUTDOWN_REQUESTED.store(false, Ordering::SeqCst);
 
     unsafe {
-        libc::signal(libc::SIGTERM, receive_signal as usize);
-        libc::signal(libc::SIGINT, receive_signal as usize);
-        libc::signal(libc::SIGUSR2, receive_signal as usize);
-        libc::signal(libc::SIGUSR1, receive_signal as usize);
-        libc::signal(libc::SIGHUP, receive_signal as usize);
-        libc::signal(libc::SIGTTIN, receive_signal as usize);
-        libc::signal(libc::SIGTTOU, receive_signal as usize);
-        libc::signal(libc::SIGCHLD, receive_signal as usize);
+        let handler = signal_handler();
+        libc::signal(libc::SIGTERM, handler);
+        libc::signal(libc::SIGINT, handler);
+        libc::signal(libc::SIGUSR2, handler);
+        libc::signal(libc::SIGUSR1, handler);
+        libc::signal(libc::SIGHUP, handler);
+        libc::signal(libc::SIGTTIN, handler);
+        libc::signal(libc::SIGTTOU, handler);
+        libc::signal(libc::SIGCHLD, handler);
     }
     true
 }

data/crates/itsi_server/src/services/itsi_http_service.rs

@@ -1,16 +1,17 @@
 use crate::default_responses::{NOT_FOUND_RESPONSE, TIMEOUT_RESPONSE};
 use crate::ruby_types::itsi_server::itsi_server_config::ItsiServerTokenPreference;
 use crate::server::http_message_types::{
-    ConversionExt, HttpRequest, HttpResponse, RequestExt, ResponseFormat,
+    ConversionExt, HttpBody, HttpRequest, HttpResponse, RequestExt, ResponseFormat,
 };
 use crate::server::lifecycle_event::LifecycleEvent;
 use crate::server::middleware_stack::MiddlewareLayer;
 use crate::server::serve_strategy::acceptor::AcceptorArgs;
 use crate::server::signal::{send_lifecycle_event, SHUTDOWN_REQUESTED};
+use bytes::Bytes;
 use chrono::{self, DateTime, Local};
 use either::Either;
 use http::header::ACCEPT_ENCODING;
-use http::{HeaderValue, Request};
+use http::{HeaderValue, Request, StatusCode};
 use hyper::body::Incoming;
 use regex::Regex;
 use smallvec::SmallVec;
@@ -174,6 +175,7 @@ impl HttpRequestContext {
 const SERVER_TOKEN_VERSION: HeaderValue =
     HeaderValue::from_static(concat!("Itsi/", env!("CARGO_PKG_VERSION")));
 const SERVER_TOKEN_NAME: HeaderValue = HeaderValue::from_static("Itsi");
+const TEXT_PLAIN_UTF8: HeaderValue = HeaderValue::from_static("text/plain; charset=utf-8");
 
 impl ItsiHttpService {
     pub async fn handle_request(&self, req: Request<Incoming>) -> itsi_error::Result<HttpResponse> {
@@ -188,6 +190,10 @@ impl ItsiHttpService {
         let token_preference = self.server_params.itsi_server_token_preference;
 
         let service_future = async move {
+            if let Some(acme_response) = self.acme_http01_response(&req) {
+                return Ok(acme_response);
+            }
+
             let Some((stack, matching_pattern)) =
                 self.server_params.middleware.get().unwrap().stack_for(&req)
             else {
@@ -264,4 +270,42 @@ impl ItsiHttpService {
             service_future.await
         }
     }
+
+    fn acme_http01_response(&self, req: &HttpRequest) -> Option<HttpResponse> {
+        let host = normalize_host_header(req.header("host")?)?;
+        let managers = self.server_params.acme_managers.read();
+        let key_authorization = managers
+            .iter()
+            .find_map(|(_, manager)| manager.http01_response(host, req.uri().path()))?;
+
+        let mut builder = http::Response::builder()
+            .status(StatusCode::OK)
+            .header(http::header::CONTENT_TYPE, TEXT_PLAIN_UTF8);
+
+        if req.method() == http::Method::HEAD {
+            builder = builder.header(http::header::CONTENT_LENGTH, "0");
+            return builder.body(HttpBody::empty()).ok();
+        }
+
+        builder
+            .header(
+                http::header::CONTENT_LENGTH,
+                key_authorization.len().to_string(),
+            )
+            .body(HttpBody::full(Bytes::from(key_authorization)))
+            .ok()
+    }
+}
+
+fn normalize_host_header(host: &str) -> Option<&str> {
+    let host = host.trim();
+    if host.is_empty() {
+        return None;
+    }
+
+    if let Some(stripped) = host.strip_prefix('[') {
+        return stripped.split(']').next();
+    }
+
+    Some(host.split(':').next().unwrap_or(host))
 }

data/docs/content/features/_index.md

@@ -145,6 +145,8 @@ Itsi also comes bundled with a passfile generator, to help you manage your passw
 * Automated provisioning of Let's Encrypt certificates.
 * File system caching of certificate data to avoid excessive API calls.
 * Supports usage of subject alternative names (SANs) for certificates that span multiple domains/sub-domains.
+* Supports direct `TLS-ALPN-01` validation and `HTTP-01` validation when a reachable HTTP listener is available.
+* Supports runtime domain registration for live certificate issuance without restarting the server.
 * See <a target="_blank" href="/options/certificates#production-certificates-lets-encrypt">certificates</a>.
 {{% /details %}}
 
@@ -225,6 +227,7 @@ Note: This is not the same as <a target="_blank" href="https://grpc.io/blog/grpc
 {{% details title="Non-blocking(Fiber Scheduler) Mode" closed="true" %}}
 * Support for Ruby’s fiber scheduler for non-blocking concurrency, boosting performance during I/O operations.
 * Use Itsi's own high-performance built-in <a target="_blank" href="/itsi_scheduler">Fiber Scheduler</a> or if your prefer you can bring your own!
+* Current native gems are built and tested across common Linux and macOS x86_64 and ARM64 targets.
 * See <a target="_blank" href="/options/fiber_scheduler">fiber_scheduler</a>.
 {{% /details %}}
 

data/docs/content/getting_started/_index.md

@@ -20,7 +20,8 @@ Install Ruby
   **Prerequisites**
 
 
-You'll need at least a C/C++ build environment and `clang` and `curl` (for running `rustup`) installed.
+Most Linux installs on common x86_64 and ARM64 targets can use the precompiled native gems directly.
+If RubyGems falls back to the source gems, you'll need a C/C++ build environment plus `clang` and `curl` (for running `rustup`).
 
 #### For Ubuntu / Debian:
 ```bash
@@ -63,6 +64,9 @@ Then use `gem` to install Itsi, or its components based on your Ruby version.
   {{< /tab >}}
   {{< tab >}}
   **Mac**:
+  Most macOS installs on Apple Silicon and Intel Macs can use the precompiled native gems directly.
+  If RubyGems falls back to the source gems, install Xcode Command Line Tools first.
+
   **For Ruby >= 3.0**:
 ```bash
     gem install itsi
@@ -88,7 +92,7 @@ Then use `gem` to install Itsi, or its components based on your Ruby version.
   {{< tab >}}
   **FreeBSD**
 
-On FreeBSD you'll need to install a few build tools manually:
+FreeBSD currently relies on source builds, so you'll need to install a few build tools manually:
 ```bash
   pkg install gmake cmake curl llvm
 ```

data/docs/content/getting_started/local_development.md

@@ -75,6 +75,19 @@ Itsi will print informative error message if config validation fails. E.g.
      |   ^^^
 ```
 
+## Local ACME Testing
+Itsi includes end-to-end ACME tests that exercise both `TLS-ALPN-01` and `HTTP-01` flows against a local [Pebble](https://github.com/letsencrypt/pebble) certificate authority.
+
+The test helper installs Pebble on demand using the Go toolchain, so the only prerequisite is a working `go` binary on your `PATH`.
+
+Once Go is available, the local ACME tests can be run as part of the normal server suite:
+
+```bash
+rake server:test
+```
+
+If Go is not installed, those specific ACME integration tests will be skipped rather than failing the whole suite.
+
 ## Shell Completions
 Itsi can also help you install shell completions, which are useful if you find yourself using the `itsi` executable a lot and forgetting the commands.
 Add the following line to the bottom of your ~/.bashrc or ~/.zshrc file: