diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index f33ca80..3166bf6 100644 --- a/DOCUMENTATION.md +++ b/DOCUMENTATION.md @@ -448,6 +448,7 @@ Content-Type: application/json "ports": { "80/tcp": "8080" }, + "bind": "loopback", "volumes": { "/host/data": "/app/data" }, @@ -455,6 +456,10 @@ Content-Type: application/json } ``` +`bind` picks the host interface every published port is bound to. It is +optional and defaults to `"loopback"`; see +[Port publishing and bind addresses](#port-publishing-and-bind-addresses). + Response (201 Created): ```json @@ -522,6 +527,75 @@ Authorization: Bearer Response: 204 No Content +### Port publishing and bind addresses + +A container port published to the host is bound to **`127.0.0.1` by default**. +Anything else has to be asked for explicitly, with a `bind` field: + +| `bind` | Host IP | Who can reach it | +| ----------------------------- | ---------------- | --------------------------------------------------------------------- | +| `"loopback"` (default) | `127.0.0.1` | This host only — local processes, SSH tunnels, and Ployer's own Caddy | +| `"all_interfaces"` | `0.0.0.0` | Every network the host is on: LAN, any VPN or tailnet, and the public internet if the router forwards the port | +| `{"address": "100.92.195.33"}`| that address | Whoever can route to that interface | + +It accepts the field on: + +- `POST /api/v1/containers` +- `POST /api/v1/templates/:slug/install` (alongside `expose` and `host_ports`) +- `PUT /api/v1/applications/:id/expose` + +Why the default is loopback: Docker publishes through its **own `DOCKER` +iptables chain, which `ufw` does not filter**. A port published on `0.0.0.0` is +reachable from the LAN whether or not a host firewall is configured, and adding +a `ufw` rule afterwards does not close it. For a database that means the +password is the only thing between the network and the data. + +The choice is recorded in the stored compose as a three-part port spec, so it +survives a redeploy and can be read back: + +```yaml +services: + postgresql: + ports: + - 127.0.0.1:15432:5432 # host-only + - 0.0.0.0:15432:5432 # every interface +``` + +A two-part spec (`15432:5432`) names no interface and therefore gets the +default. **This is a behaviour change**: services installed before this +existed have two-part specs, so the next redeploy moves them from `0.0.0.0` to +`127.0.0.1`. To keep LAN access, pick "All interfaces" on the application's +page and save — the redeploy writes the interface into the compose explicitly. + +Reaching a loopback-bound service from another machine, without republishing +it: + +```bash +ssh -L 15432:127.0.0.1:15432 user@ployer-host +``` + +Applications deployed from git are always loopback-bound on a Docker-assigned +ephemeral port. Caddy runs on the host and proxies to `localhost:`, so +outside traffic arrives through the reverse proxy, which owns 80/443 and TLS. + +### Restart policies + +A service template's `restart:` is honoured. A template that declares + +```yaml +services: + oneshot: + image: busybox + restart: "no" +``` + +gets Docker's `no` policy, not `unless-stopped`. Accepted values are `no`, +`always`, `unless-stopped` and `on-failure[:max-retries]`; anything else fails +the deploy with an error rather than silently falling back. + +A template that declares nothing, and every application deployed from git, +still gets `unless-stopped` so containers come back after a host reboot. + ### Network Management **List networks** diff --git a/crates/ployer-api/src/routes/applications.rs b/crates/ployer-api/src/routes/applications.rs index 265b6eb..b87a62a 100644 --- a/crates/ployer-api/src/routes/applications.rs +++ b/crates/ployer-api/src/routes/applications.rs @@ -15,6 +15,7 @@ use crate::services::deployment::DeploymentService; use ployer_core::crypto; use ployer_core::models::{Application, BuildStrategy}; use ployer_db::repositories::{ApplicationRepository, DeployKeyRepository, EnvVarRepository, SettingsRepository}; +use ployer_docker::BindAddress; use ployer_git::GitService; pub fn router() -> Router { @@ -411,6 +412,10 @@ struct UpdateExposeRequest { expose: bool, #[serde(default)] host_ports: HashMap, + /// Which host interface to publish on. Defaults to loopback; see + /// `ployer_docker::BindAddress`. + #[serde(default)] + bind: BindAddress, } #[derive(Debug, Serialize)] @@ -469,8 +474,12 @@ async fn update_expose( .iter() .map(|p| (p.container, *req.host_ports.get(&p.container).unwrap_or(&p.container))) .collect(); - new_compose = ployer_templates::compose::add_ports_to_all_services(&new_compose, &bindings) - .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?; + new_compose = ployer_templates::compose::add_ports_to_all_services( + &new_compose, + &bindings, + req.bind.host_ip(), + ) + .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?; } app_repo diff --git a/crates/ployer-api/src/routes/containers.rs b/crates/ployer-api/src/routes/containers.rs index 415eac5..0e54d08 100644 --- a/crates/ployer-api/src/routes/containers.rs +++ b/crates/ployer-api/src/routes/containers.rs @@ -11,7 +11,10 @@ use crate::app_state::SharedState; use crate::auth::extract_user_id; use ployer_core::models::AppStatus; use ployer_db::repositories::ApplicationRepository; -use ployer_docker::{ContainerConfig, ContainerInfo, ContainerStats, NetworkInfo, VolumeInfo}; +use ployer_docker::{ + BindAddress, ContainerConfig, ContainerInfo, ContainerStats, NetworkInfo, PublishedPort, + VolumeInfo, +}; // Reconcile the owning application's stored status with the container's actual // state in Docker. The convention is that Ployer-managed containers are named @@ -88,10 +91,16 @@ struct CreateContainerRequest { image: String, name: Option, env: Option>, + /// container_port (e.g. `"80/tcp"`) -> host port. An empty host port lets + /// Docker pick a free ephemeral one. ports: Option>, volumes: Option>, network: Option, cmd: Option>, + /// Host interface every published port is bound to. Defaults to loopback; + /// see `ployer_docker::BindAddress`. + #[serde(default)] + bind: BindAddress, } #[derive(Debug, Serialize)] @@ -167,11 +176,21 @@ async fn create_container( return Err((StatusCode::BAD_REQUEST, "Image name is required".to_string())); } + // Every published port lands on the same interface — the request carries + // one `bind` for the whole container. + let bind = req.bind.clone(); let config = ContainerConfig { image: req.image, name: req.name, env: req.env, - ports: req.ports, + ports: req.ports.map(|ports| { + ports + .into_iter() + .map(|(container_port, host_port)| { + (container_port, PublishedPort::new(bind.clone(), host_port)) + }) + .collect() + }), volumes: req.volumes, network: req.network, cmd: req.cmd, diff --git a/crates/ployer-api/src/routes/templates.rs b/crates/ployer-api/src/routes/templates.rs index 5cb28de..9f7ab48 100644 --- a/crates/ployer-api/src/routes/templates.rs +++ b/crates/ployer-api/src/routes/templates.rs @@ -8,6 +8,7 @@ use axum::{ Json, Router, }; use ployer_core::crypto; +use ployer_docker::BindAddress; use ployer_db::repositories::{ApplicationRepository, EnvVarRepository}; use ployer_templates::{render, Template, TemplateError}; use ployer_templates::render::RenderContext; @@ -84,6 +85,13 @@ struct InstallRequest { /// Map of container_port -> host_port. Only used when `expose` is true. #[serde(default)] host_ports: HashMap, + /// Which host interface to publish on when `expose` is true. Defaults to + /// loopback — `all_interfaces` makes the service reachable from the LAN, + /// from any VPN the host has joined, and from the internet if the router + /// forwards the port, and Docker's publishing is not filtered by a host + /// firewall such as ufw. + #[serde(default)] + bind: BindAddress, } #[derive(Debug, Serialize)] @@ -136,9 +144,12 @@ async fn install_template( .iter() .map(|p| (p.container, *req.host_ports.get(&p.container).unwrap_or(&p.container))) .collect(); - rendered.compose = - ployer_templates::compose::add_ports_to_all_services(&rendered.compose, &bindings) - .map_err(map_err)?; + rendered.compose = ployer_templates::compose::add_ports_to_all_services( + &rendered.compose, + &bindings, + req.bind.host_ip(), + ) + .map_err(map_err)?; } // Persist application + env vars. diff --git a/crates/ployer-api/src/services/deployment.rs b/crates/ployer-api/src/services/deployment.rs index 8bdcbc5..da40487 100644 --- a/crates/ployer-api/src/services/deployment.rs +++ b/crates/ployer-api/src/services/deployment.rs @@ -1,7 +1,7 @@ use anyhow::{anyhow, Result}; use ployer_core::models::{AppStatus, Application, Deployment, DeploymentStatus, WsEvent}; use ployer_db::repositories::{ApplicationRepository, DeploymentRepository, DomainRepository, EnvVarRepository, SettingsRepository}; -use ployer_docker::{DockerClient, ContainerConfig}; +use ployer_docker::{BindAddress, DockerClient, ContainerConfig, PublishedPort}; use ployer_git::GitService; use ployer_proxy::{CaddyClient, RouteSpec}; use sqlx::SqlitePool; @@ -277,7 +277,12 @@ impl DeploymentService { // bind the container's own port (e.g. 80) on the host, or apps // that EXPOSE 80 collide with each other and with the reverse // proxy. Caddy is pointed at the assigned port after start. - ports.insert(format!("{}/tcp", p), String::new()); + // + // Loopback-bound: Caddy runs on the host and reaches the app + // over localhost, so the published port never has to leave the + // machine. Traffic from outside arrives through Caddy, which + // owns 80/443 and the TLS. + ports.insert(format!("{}/tcp", p), PublishedPort::ephemeral()); ports }), volumes: None, @@ -562,9 +567,31 @@ impl DeploymentService { let mut ports_map = HashMap::new(); for port_spec in &service.ports { - if let Some((host, container)) = ployer_templates::compose::split_port(port_spec) { - ports_map.insert(format!("{}/tcp", container), host); + let mapping = ployer_templates::compose::parse_port_spec(port_spec) + .ok_or_else(|| anyhow!("invalid port spec: {port_spec}"))?; + let bind = BindAddress::from_host_ip(mapping.host_ip.as_deref()); + + // Say out loud, in the deploy log, what the host just published + // and to whom. A compose written before bind addresses existed + // names no interface and so lands on the loopback default. + if bind.is_loopback_only() { + send_log(format!( + "Publishing {} -> {}:{} (this host only)", + mapping.container_port, bind.host_ip(), mapping.host_port + )) + .await; + } else { + send_log(format!( + "Warning: publishing {} -> {}:{} — reachable from every network this host is on (LAN, VPN, and the internet if your router forwards it). Docker publishes through its own iptables chain, so a ufw rule will not filter this.", + mapping.container_port, bind.host_ip(), mapping.host_port + )) + .await; } + + ports_map.insert( + format!("{}/tcp", mapping.container_port), + PublishedPort::new(bind, mapping.host_port), + ); } let ports = if ports_map.is_empty() { None } else { Some(ports_map) }; @@ -579,7 +606,9 @@ impl DeploymentService { cmd: None, cpu_limit: application.cpu_limit, memory_limit: application.memory_limit, - restart: None, + // Honour the template's declared policy. None (the common case) + // still means "unless-stopped". + restart: service.restart.clone(), }; let container_id = docker.create_container(config).await?; diff --git a/crates/ployer-docker/src/lib.rs b/crates/ployer-docker/src/lib.rs index 994d489..b8bd63f 100644 --- a/crates/ployer-docker/src/lib.rs +++ b/crates/ployer-docker/src/lib.rs @@ -1,4 +1,4 @@ -use anyhow::Result; +use anyhow::{anyhow, Result}; use bollard::container::{ Config, CreateContainerOptions, InspectContainerOptions, ListContainersOptions, LogsOptions, RemoveContainerOptions, StartContainerOptions, StatsOptions, StopContainerOptions, @@ -33,6 +33,166 @@ const DEFAULT_LOG_MAX_FILE: &str = "5"; /// maintenance operations to Ployer-managed containers only. const MANAGED_CONTAINER_PREFIX: &str = "ployer-"; +/// Docker restart policy applied when neither the caller nor the template +/// names one, so containers come back after a host reboot. +const DEFAULT_RESTART_POLICY: &str = "unless-stopped"; + +const LOOPBACK_IP: &str = "127.0.0.1"; +const ALL_INTERFACES_IP: &str = "0.0.0.0"; + +/// Docker's `ExposedPorts` map: `"5432/tcp" -> {}`. +type ExposedPorts = HashMap>; +/// Docker's `HostConfig.PortBindings` map: `"5432/tcp" -> [binding]`. +type PortBindings = HashMap>>; + +/// Which host interface a published container port is bound to. +/// +/// Defaults to [`BindAddress::Loopback`]. Publishing on every interface makes +/// a service reachable from the LAN, from any VPN or tailnet the host has +/// joined, and from the public internet if the router forwards the port. +/// Docker publishes through its own `DOCKER` iptables chain, which a host +/// firewall such as `ufw` does not filter, so "I'll add a firewall rule later" +/// does not close it. Callers that want that reach have to ask for it. +#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum BindAddress { + /// `127.0.0.1` — reachable from this host only, including the host's own + /// reverse proxy. The default. + #[default] + Loopback, + /// `0.0.0.0` — reachable from every network this host is attached to. + AllInterfaces, + /// One specific host interface, e.g. the host's tailnet address. + Address(String), +} + +impl BindAddress { + /// The literal address handed to Docker as `PortBindings[].HostIp`. + pub fn host_ip(&self) -> &str { + match self { + BindAddress::Loopback => LOOPBACK_IP, + BindAddress::AllInterfaces => ALL_INTERFACES_IP, + BindAddress::Address(addr) => addr, + } + } + + /// Classify a host IP read back out of a compose file or a container. + /// + /// Absent or empty means the spec did not say, which is how every compose + /// file written before this existed looks. Those resolve to the default, + /// [`BindAddress::Loopback`] — redeploying an older service moves it off + /// `0.0.0.0` unless the operator re-picks `AllInterfaces`. + pub fn from_host_ip(ip: Option<&str>) -> Self { + match ip.map(str::trim).filter(|s| !s.is_empty()) { + None => BindAddress::Loopback, + Some(LOOPBACK_IP) => BindAddress::Loopback, + Some(ALL_INTERFACES_IP) => BindAddress::AllInterfaces, + Some(other) => BindAddress::Address(other.to_string()), + } + } + + /// True when the binding cannot be reached from another machine. + pub fn is_loopback_only(&self) -> bool { + match self { + BindAddress::Loopback => true, + BindAddress::AllInterfaces => false, + BindAddress::Address(addr) => addr == "::1" || addr.starts_with("127."), + } + } +} + +/// One published container port: the host interface it is bound to and the +/// host port it claims. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct PublishedPort { + #[serde(default)] + pub bind: BindAddress, + /// Host port. Empty means "let Docker pick a free ephemeral port", which + /// is what the application deploy path relies on so apps that `EXPOSE 80` + /// do not collide with each other or with the reverse proxy. + pub host_port: String, +} + +impl PublishedPort { + pub fn new(bind: BindAddress, host_port: impl Into) -> Self { + Self { bind, host_port: host_port.into() } + } + + /// Loopback-bound on a Docker-assigned ephemeral host port. + pub fn ephemeral() -> Self { + Self::new(BindAddress::Loopback, "") + } +} + +/// A Docker restart policy plus its optional retry cap (`on-failure:5`). +#[derive(Debug, Clone, PartialEq, Eq)] +struct RestartSpec { + name: RestartPolicyNameEnum, + max_retries: Option, +} + +/// Map a compose/[`ContainerConfig`] restart string onto Docker's enum. +/// +/// `None` (and an empty string) means the caller has no opinion and gets +/// [`DEFAULT_RESTART_POLICY`]. An unrecognised name is an error rather than a +/// silent fallback: a template asking for `restart: "nope"` should fail the +/// install loudly instead of quietly running `unless-stopped`. +fn parse_restart_policy(spec: Option<&str>) -> Result { + let spec = spec.map(str::trim).filter(|s| !s.is_empty()).unwrap_or(DEFAULT_RESTART_POLICY); + let (name, retries) = match spec.split_once(':') { + Some((name, retries)) => (name, Some(retries)), + None => (spec, None), + }; + + let policy = match name { + "no" => RestartPolicyNameEnum::NO, + "always" => RestartPolicyNameEnum::ALWAYS, + "unless-stopped" => RestartPolicyNameEnum::UNLESS_STOPPED, + "on-failure" => RestartPolicyNameEnum::ON_FAILURE, + other => { + return Err(anyhow!( + "unknown restart policy {other:?} (expected no, always, unless-stopped or on-failure[:max-retries])" + )) + } + }; + + let max_retries = match (policy, retries) { + (_, None) => None, + (RestartPolicyNameEnum::ON_FAILURE, Some(n)) => Some( + n.parse::() + .map_err(|_| anyhow!("restart policy {spec:?} has a non-numeric retry count"))?, + ), + (_, Some(_)) => { + return Err(anyhow!("restart policy {spec:?} takes no retry count (only on-failure does)")) + } + }; + + Ok(RestartSpec { name: policy, max_retries }) +} + +/// Build Docker's `ExposedPorts` and `PortBindings` for a set of published +/// ports. +/// +/// Split out of [`DockerClient::create_container`] and kept pure so the host +/// interface each port lands on can be asserted without a Docker daemon. +fn build_port_bindings(ports: &HashMap) -> (ExposedPorts, PortBindings) { + let mut exposed_ports: ExposedPorts = HashMap::new(); + let mut port_bindings: PortBindings = HashMap::new(); + + for (container_port, publish) in ports { + exposed_ports.insert(container_port.clone(), HashMap::new()); + port_bindings.insert( + container_port.clone(), + Some(vec![PortBinding { + host_ip: Some(publish.bind.host_ip().to_string()), + host_port: Some(publish.host_port.clone()), + }]), + ); + } + + (exposed_ports, port_bindings) +} + pub struct DockerClient { client: Docker, } @@ -43,13 +203,13 @@ pub struct ContainerConfig { pub image: String, pub name: Option, pub env: Option>, - pub ports: Option>, // container_port -> host_port + pub ports: Option>, // container_port -> publication pub volumes: Option>, // host_path -> container_path pub network: Option, pub cmd: Option>, pub cpu_limit: Option, // CPU cores (e.g. 0.5 = half a core) pub memory_limit: Option, // Memory in MB - // Docker restart policy: "no" | "always" | "unless-stopped" | "on-failure". + // Docker restart policy: "no" | "always" | "unless-stopped" | "on-failure[:n]". // None defaults to "unless-stopped" so containers survive host reboots. pub restart: Option, } @@ -291,27 +451,18 @@ impl DockerClient { info!("Creating container with config: {:?}", config); // Build exposed ports and port bindings - let mut exposed_ports: HashMap> = HashMap::new(); - let mut port_bindings = HashMap::new(); - if let Some(ports) = &config.ports { - info!("Configuring ports: {:?}", ports); - for (container_port, host_port) in ports { - // Expose the port in the container - exposed_ports.insert(container_port.clone(), HashMap::new()); - - // Bind the port to the host - port_bindings.insert( - container_port.clone(), - Some(vec![PortBinding { - host_ip: Some("0.0.0.0".to_string()), - host_port: Some(host_port.clone()), - }]), - ); + let (exposed_ports, port_bindings) = match &config.ports { + Some(ports) => { + info!("Configuring ports: {:?}", ports); + let built = build_port_bindings(ports); + info!("Port bindings configured: {:?}", built.1); + built } - info!("Port bindings configured: {:?}", port_bindings); - } else { - warn!("No ports configured in ContainerConfig!"); - } + None => { + warn!("No ports configured in ContainerConfig!"); + (ExposedPorts::new(), PortBindings::new()) + } + }; // Build volume bindings let binds = config.volumes.as_ref().map(|volumes| { @@ -324,13 +475,9 @@ impl DockerClient { let nano_cpus = config.cpu_limit.map(|c| (c * 1_000_000_000.0) as i64); let memory = config.memory_limit.map(|m| m * 1024 * 1024); // MB to bytes - // Default to "unless-stopped" so containers come back after a host reboot. - let restart_policy_name = match config.restart.as_deref().unwrap_or("unless-stopped") { - "no" => RestartPolicyNameEnum::NO, - "always" => RestartPolicyNameEnum::ALWAYS, - "on-failure" => RestartPolicyNameEnum::ON_FAILURE, - _ => RestartPolicyNameEnum::UNLESS_STOPPED, - }; + // Honour the caller's (and therefore the template's) restart policy. + // Unnamed means "unless-stopped" so containers come back after a reboot. + let restart = parse_restart_policy(config.restart.as_deref())?; // Cap captured stdout/stderr logs so no single container can fill the host // disk (which would break Ployer's own SQLite database). @@ -350,8 +497,8 @@ impl DockerClient { nano_cpus, memory, restart_policy: Some(RestartPolicy { - name: Some(restart_policy_name), - maximum_retry_count: None, + name: Some(restart.name), + maximum_retry_count: restart.max_retries, }), ..Default::default() }); diff --git a/crates/ployer-docker/src/tests.rs b/crates/ployer-docker/src/tests.rs index 43f885b..81add83 100644 --- a/crates/ployer-docker/src/tests.rs +++ b/crates/ployer-docker/src/tests.rs @@ -15,6 +15,20 @@ fn make_config(cpu: Option, mem_mb: Option) -> ContainerConfig { } } +fn published(ports: &[(&str, PublishedPort)]) -> HashMap { + ports.iter().map(|(p, b)| (p.to_string(), b.clone())).collect() +} + +/// The HostIp Docker would be handed for `container_port`. +fn bound_host_ip(bindings: &PortBindings, container_port: &str) -> String { + bindings + .get(container_port) + .and_then(|b| b.as_ref()) + .and_then(|b| b.first()) + .and_then(|b| b.host_ip.clone()) + .unwrap_or_else(|| panic!("no binding for {container_port}")) +} + #[test] fn cpu_limit_converts_to_nano_cpus() { // 0.5 cores = 500_000_000 nano_cpus @@ -62,3 +76,158 @@ fn container_config_fields_are_set() { assert_eq!(config.cpu_limit, Some(2.0)); assert_eq!(config.memory_limit, Some(256)); } + +// ===== Bind address ===== +// +// These pin the host interface a published port lands on. The whole point of +// the type is that nobody reaches a database over the LAN by accident, so the +// default and the explicit opt-in both get asserted. + +#[test] +fn bind_address_defaults_to_loopback() { + assert_eq!(BindAddress::default(), BindAddress::Loopback); + assert_eq!(BindAddress::default().host_ip(), "127.0.0.1"); +} + +#[test] +fn bind_address_maps_variants_to_host_ips() { + assert_eq!(BindAddress::Loopback.host_ip(), "127.0.0.1"); + assert_eq!(BindAddress::AllInterfaces.host_ip(), "0.0.0.0"); + assert_eq!(BindAddress::Address("100.92.195.33".into()).host_ip(), "100.92.195.33"); +} + +#[test] +fn an_unspecified_host_ip_resolves_to_loopback_not_all_interfaces() { + // Compose files written before this existed carry "15432:5432" with no + // interface. They must not keep landing on 0.0.0.0 by omission. + assert_eq!(BindAddress::from_host_ip(None), BindAddress::Loopback); + assert_eq!(BindAddress::from_host_ip(Some("")), BindAddress::Loopback); + assert_eq!(BindAddress::from_host_ip(Some(" ")), BindAddress::Loopback); +} + +#[test] +fn from_host_ip_round_trips_the_named_variants() { + assert_eq!(BindAddress::from_host_ip(Some("127.0.0.1")), BindAddress::Loopback); + assert_eq!(BindAddress::from_host_ip(Some("0.0.0.0")), BindAddress::AllInterfaces); + assert_eq!( + BindAddress::from_host_ip(Some("192.168.100.100")), + BindAddress::Address("192.168.100.100".into()) + ); +} + +#[test] +fn only_loopback_addresses_count_as_host_only() { + assert!(BindAddress::Loopback.is_loopback_only()); + assert!(BindAddress::Address("127.0.0.53".into()).is_loopback_only()); + assert!(BindAddress::Address("::1".into()).is_loopback_only()); + assert!(!BindAddress::AllInterfaces.is_loopback_only()); + assert!(!BindAddress::Address("192.168.100.100".into()).is_loopback_only()); + // A tailnet address is still another machine's route in. + assert!(!BindAddress::Address("100.92.195.33".into()).is_loopback_only()); +} + +#[test] +fn published_ports_bind_where_the_config_says() { + let (_, bindings) = build_port_bindings(&published(&[ + ("5432/tcp", PublishedPort::new(BindAddress::Loopback, "15432")), + ("3306/tcp", PublishedPort::new(BindAddress::AllInterfaces, "3306")), + ("8096/tcp", PublishedPort::new(BindAddress::Address("100.92.195.33".into()), "8096")), + ])); + + assert_eq!(bound_host_ip(&bindings, "5432/tcp"), "127.0.0.1"); + assert_eq!(bound_host_ip(&bindings, "3306/tcp"), "0.0.0.0"); + assert_eq!(bound_host_ip(&bindings, "8096/tcp"), "100.92.195.33"); +} + +#[test] +fn an_ephemeral_port_is_loopback_bound_with_an_empty_host_port() { + // The app deploy path relies on the empty host port for Docker's ephemeral + // assignment, and Caddy reaches it over localhost — so it never needs to + // leave the host. + let publish = PublishedPort::ephemeral(); + assert_eq!(publish.bind, BindAddress::Loopback); + assert_eq!(publish.host_port, ""); + + let (exposed, bindings) = build_port_bindings(&published(&[("3000/tcp", publish)])); + assert_eq!(bound_host_ip(&bindings, "3000/tcp"), "127.0.0.1"); + assert_eq!( + bindings["3000/tcp"].as_ref().unwrap()[0].host_port, + Some(String::new()) + ); + assert!(exposed.contains_key("3000/tcp")); +} + +#[test] +fn every_published_port_is_also_exposed() { + let (exposed, bindings) = build_port_bindings(&published(&[ + ("5432/tcp", PublishedPort::new(BindAddress::Loopback, "15432")), + ("5433/tcp", PublishedPort::new(BindAddress::Loopback, "15433")), + ])); + assert_eq!(exposed.len(), 2); + assert_eq!(bindings.len(), 2); +} + +#[test] +fn bind_address_serde_uses_snake_case_tags() { + assert_eq!(serde_json::to_string(&BindAddress::Loopback).unwrap(), "\"loopback\""); + assert_eq!( + serde_json::to_string(&BindAddress::AllInterfaces).unwrap(), + "\"all_interfaces\"" + ); + assert_eq!( + serde_json::from_str::("\"all_interfaces\"").unwrap(), + BindAddress::AllInterfaces + ); + assert_eq!( + serde_json::from_str::("{\"address\":\"100.92.195.33\"}").unwrap(), + BindAddress::Address("100.92.195.33".into()) + ); +} + +#[test] +fn a_published_port_without_a_bind_field_deserializes_to_loopback() { + let publish: PublishedPort = serde_json::from_str("{\"host_port\":\"15432\"}").unwrap(); + assert_eq!(publish.bind, BindAddress::Loopback); +} + +// ===== Restart policy ===== + +#[test] +fn an_unnamed_restart_policy_defaults_to_unless_stopped() { + let spec = parse_restart_policy(None).unwrap(); + assert_eq!(spec.name, RestartPolicyNameEnum::UNLESS_STOPPED); + assert_eq!(spec.max_retries, None); + // An empty string is the same "no opinion". + assert_eq!(parse_restart_policy(Some("")).unwrap().name, RestartPolicyNameEnum::UNLESS_STOPPED); +} + +#[test] +fn a_declared_restart_policy_is_honoured_not_overridden() { + // A template asking for `restart: "no"` used to silently get + // unless-stopped. It gets what it asked for. + assert_eq!(parse_restart_policy(Some("no")).unwrap().name, RestartPolicyNameEnum::NO); + assert_eq!(parse_restart_policy(Some("always")).unwrap().name, RestartPolicyNameEnum::ALWAYS); + assert_eq!( + parse_restart_policy(Some("on-failure")).unwrap().name, + RestartPolicyNameEnum::ON_FAILURE + ); + assert_eq!( + parse_restart_policy(Some("unless-stopped")).unwrap().name, + RestartPolicyNameEnum::UNLESS_STOPPED + ); +} + +#[test] +fn on_failure_carries_its_retry_cap() { + let spec = parse_restart_policy(Some("on-failure:5")).unwrap(); + assert_eq!(spec.name, RestartPolicyNameEnum::ON_FAILURE); + assert_eq!(spec.max_retries, Some(5)); +} + +#[test] +fn an_unknown_restart_policy_is_an_error_not_a_silent_fallback() { + let err = parse_restart_policy(Some("nope")).unwrap_err().to_string(); + assert!(err.contains("nope"), "{err}"); + assert!(parse_restart_policy(Some("always:3")).is_err()); + assert!(parse_restart_policy(Some("on-failure:many")).is_err()); +} diff --git a/crates/ployer-templates/src/compose.rs b/crates/ployer-templates/src/compose.rs index 9e4e69b..4d22397 100644 --- a/crates/ployer-templates/src/compose.rs +++ b/crates/ployer-templates/src/compose.rs @@ -77,13 +77,18 @@ pub fn remove_ports_from_all_services(yaml: &str) -> Result Result, TemplateError> { let spec: ComposeSpec = serde_yaml::from_str(yaml)?; let mut out = Vec::new(); for (_, svc) in spec.services { for port_str in svc.ports { - if let Some((host_s, container_s)) = split_port(&port_str) { - if let (Ok(h), Ok(c)) = (host_s.parse::(), container_s.parse::()) { + if let Some(mapping) = parse_port_spec(&port_str) { + if let (Ok(h), Ok(c)) = ( + mapping.host_port.parse::(), + mapping.container_port.parse::(), + ) { out.push((c, h)); } } @@ -94,10 +99,14 @@ pub fn current_port_bindings(yaml: &str) -> Result, TemplateErro /// Inject a `ports` mapping into every service in the compose YAML. Used by /// the install endpoint when the user opts to expose a template's port to -/// the host. `bindings` maps `container_port -> host_port`. +/// the host. `bindings` maps `container_port -> host_port`, and `host_ip` is +/// the interface to publish on — always written out explicitly so the stored +/// compose records which interface was chosen rather than leaving it to +/// whatever the deployer's default happens to be. pub fn add_ports_to_all_services( yaml: &str, bindings: &[(u16, u16)], + host_ip: &str, ) -> Result { if bindings.is_empty() { return Ok(yaml.to_string()); @@ -115,7 +124,7 @@ pub fn add_ports_to_all_services( let port_seq: Vec = bindings .iter() .map(|(container, host)| { - serde_yaml::Value::String(format!("{}:{}", host, container)) + serde_yaml::Value::String(format_port_spec(host_ip, *host, *container)) }) .collect(); @@ -140,11 +149,75 @@ pub fn split_volume(spec: &str) -> Option<(String, String)> { Some((host, container)) } -/// Split `host:container` or `container` port spec. +/// A parsed docker-compose short-syntax port mapping. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct PortMapping { + /// Host interface the port is published on. `None` when the spec does not + /// name one (`"15432:5432"`), which leaves the choice to the deployer. + pub host_ip: Option, + pub host_port: String, + pub container_port: String, +} + +/// Parse one compose short-syntax `ports:` entry. +/// +/// Handles `container`, `host:container` and `host_ip:host:container`, +/// including a bracketed IPv6 host address (`[::1]:15432:5432`). Returns +/// `None` for anything else, including empty components. +/// +/// Note that a bare `"5432"` is read as host 5432 -> container 5432. Compose +/// itself would give that an ephemeral host port; Ployer has always read it +/// the other way and templates never emit the bare form, so this keeps the +/// existing behaviour rather than silently moving anyone's port. +pub fn parse_port_spec(spec: &str) -> Option { + let spec = spec.trim(); + + // Bracketed IPv6 host address: [::1]:15432:5432 + if let Some(rest) = spec.strip_prefix('[') { + let (ip, rest) = rest.split_once(']')?; + let (host_port, container_port) = rest.strip_prefix(':')?.split_once(':')?; + return port_mapping(Some(ip), host_port, container_port); + } + + let parts: Vec<&str> = spec.split(':').collect(); + match parts.as_slice() { + [port] => port_mapping(None, port, port), + [host_port, container_port] => port_mapping(None, host_port, container_port), + [ip, host_port, container_port] => port_mapping(Some(ip), host_port, container_port), + _ => None, + } +} + +fn port_mapping(ip: Option<&str>, host_port: &str, container_port: &str) -> Option { + if host_port.is_empty() || container_port.is_empty() { + return None; + } + Some(PortMapping { + host_ip: ip.map(|s| s.trim().to_string()).filter(|s| !s.is_empty()), + host_port: host_port.to_string(), + container_port: container_port.to_string(), + }) +} + +/// Split a port spec into `(host_port, container_port)`, discarding any host +/// interface. Prefer [`parse_port_spec`], which keeps it. pub fn split_port(spec: &str) -> Option<(String, String)> { - if let Some((host, container)) = spec.split_once(':') { - Some((host.to_string(), container.to_string())) + parse_port_spec(spec).map(|m| (m.host_port, m.container_port)) +} + +/// Render a compose `ports:` entry. An empty `host_ip` omits the interface; +/// an IPv6 literal is bracketed so it round-trips through [`parse_port_spec`]. +fn format_port_spec(host_ip: &str, host_port: u16, container_port: u16) -> String { + let ip = host_ip.trim(); + if ip.is_empty() { + format!("{}:{}", host_port, container_port) + } else if ip.contains(':') { + format!("[{}]:{}:{}", ip, host_port, container_port) } else { - Some((spec.to_string(), spec.to_string())) + format!("{}:{}:{}", ip, host_port, container_port) } } + +#[cfg(test)] +#[path = "compose_tests.rs"] +mod tests; diff --git a/crates/ployer-templates/src/compose_tests.rs b/crates/ployer-templates/src/compose_tests.rs new file mode 100644 index 0000000..9ff2009 --- /dev/null +++ b/crates/ployer-templates/src/compose_tests.rs @@ -0,0 +1,198 @@ +use super::*; + +/// A rendered single-service compose, shaped like what `render()` produces for +/// the postgresql template. +const RENDERED: &str = r#" +services: + postgresql: + image: postgres:17-alpine + environment: + POSTGRES_PASSWORD: hunter2 + volumes: + - ployer_demo_data:/var/lib/postgresql/data + networks: + - ployer +"#; + +fn ports_of(yaml: &str) -> Vec { + parse(yaml) + .unwrap() + .services + .into_values() + .flat_map(|s| s.ports) + .collect() +} + +// ===== parse_port_spec ===== + +#[test] +fn a_bare_port_maps_to_itself() { + assert_eq!( + parse_port_spec("5432"), + Some(PortMapping { + host_ip: None, + host_port: "5432".into(), + container_port: "5432".into() + }) + ); +} + +#[test] +fn host_and_container_parse_without_an_interface() { + assert_eq!( + parse_port_spec("15432:5432"), + Some(PortMapping { + host_ip: None, + host_port: "15432".into(), + container_port: "5432".into() + }) + ); +} + +#[test] +fn a_host_interface_is_kept_not_folded_into_the_host_port() { + // The bug this guards: splitting on the first ':' read the interface as + // the host port and "15432:5432" as the container port. + assert_eq!( + parse_port_spec("127.0.0.1:15432:5432"), + Some(PortMapping { + host_ip: Some("127.0.0.1".into()), + host_port: "15432".into(), + container_port: "5432".into() + }) + ); +} + +#[test] +fn all_interfaces_parses_like_any_other_interface() { + assert_eq!( + parse_port_spec("0.0.0.0:3306:3306"), + Some(PortMapping { + host_ip: Some("0.0.0.0".into()), + host_port: "3306".into(), + container_port: "3306".into() + }) + ); +} + +#[test] +fn a_bracketed_ipv6_interface_parses() { + assert_eq!( + parse_port_spec("[::1]:15432:5432"), + Some(PortMapping { + host_ip: Some("::1".into()), + host_port: "15432".into(), + container_port: "5432".into() + }) + ); +} + +#[test] +fn malformed_port_specs_are_rejected() { + assert_eq!(parse_port_spec(""), None); + assert_eq!(parse_port_spec(":5432"), None); + assert_eq!(parse_port_spec("15432:"), None); + assert_eq!(parse_port_spec("1:2:3:4"), None); + assert_eq!(parse_port_spec("[::1]5432:5432"), None); +} + +#[test] +fn split_port_drops_the_interface() { + assert_eq!(split_port("5432"), Some(("5432".into(), "5432".into()))); + assert_eq!(split_port("15432:5432"), Some(("15432".into(), "5432".into()))); + assert_eq!( + split_port("0.0.0.0:15432:5432"), + Some(("15432".into(), "5432".into())) + ); +} + +// ===== add_ports_to_all_services ===== + +#[test] +fn publishing_writes_the_interface_into_the_compose() { + let out = add_ports_to_all_services(RENDERED, &[(5432, 15432)], "127.0.0.1").unwrap(); + assert_eq!(ports_of(&out), vec!["127.0.0.1:15432:5432"]); +} + +#[test] +fn publishing_on_all_interfaces_is_spelled_out_not_implied() { + // The stored compose has to record which interface was chosen, so nothing + // downstream has to guess and so the operator can read it back. + let out = add_ports_to_all_services(RENDERED, &[(5432, 15432)], "0.0.0.0").unwrap(); + assert_eq!(ports_of(&out), vec!["0.0.0.0:15432:5432"]); +} + +#[test] +fn an_empty_interface_falls_back_to_the_two_part_form() { + let out = add_ports_to_all_services(RENDERED, &[(5432, 15432)], "").unwrap(); + assert_eq!(ports_of(&out), vec!["15432:5432"]); +} + +#[test] +fn an_ipv6_interface_is_bracketed_so_it_round_trips() { + let out = add_ports_to_all_services(RENDERED, &[(5432, 15432)], "::1").unwrap(); + assert_eq!(ports_of(&out), vec!["[::1]:15432:5432"]); + assert_eq!( + parse_port_spec(&ports_of(&out)[0]).unwrap().host_ip, + Some("::1".into()) + ); +} + +#[test] +fn no_bindings_leaves_the_compose_alone() { + let out = add_ports_to_all_services(RENDERED, &[], "0.0.0.0").unwrap(); + assert_eq!(out, RENDERED); +} + +#[test] +fn republishing_replaces_the_previous_interface() { + let public = add_ports_to_all_services(RENDERED, &[(5432, 15432)], "0.0.0.0").unwrap(); + let private = add_ports_to_all_services(&public, &[(5432, 15432)], "127.0.0.1").unwrap(); + assert_eq!(ports_of(&private), vec!["127.0.0.1:15432:5432"]); +} + +#[test] +fn unpublishing_removes_the_interface_too() { + let published = add_ports_to_all_services(RENDERED, &[(5432, 15432)], "0.0.0.0").unwrap(); + let unpublished = remove_ports_from_all_services(&published).unwrap(); + assert!(ports_of(&unpublished).is_empty()); +} + +// ===== current_port_bindings ===== + +#[test] +fn current_bindings_read_a_three_part_spec() { + let published = add_ports_to_all_services(RENDERED, &[(5432, 15432)], "127.0.0.1").unwrap(); + assert_eq!(current_port_bindings(&published).unwrap(), vec![(5432, 15432)]); +} + +#[test] +fn current_bindings_still_read_a_two_part_spec() { + let published = add_ports_to_all_services(RENDERED, &[(5432, 15432)], "").unwrap(); + assert_eq!(current_port_bindings(&published).unwrap(), vec![(5432, 15432)]); +} + +#[test] +fn current_bindings_are_empty_when_nothing_is_published() { + assert!(current_port_bindings(RENDERED).unwrap().is_empty()); +} + +// ===== restart ===== + +#[test] +fn a_declared_restart_policy_survives_parsing() { + // It is not enough that the field exists; the deploy path reads it, so a + // template asking for "no" has to arrive as Some("no"). + let yaml = r#" +services: + app: + image: nginx:alpine + restart: "no" +"#; + assert_eq!(parse(yaml).unwrap().services["app"].restart.as_deref(), Some("no")); +} + +#[test] +fn an_absent_restart_policy_parses_as_none() { + assert_eq!(parse(RENDERED).unwrap().services["postgresql"].restart, None); +} diff --git a/frontend/src/routes/applications/[id]/+page.svelte b/frontend/src/routes/applications/[id]/+page.svelte index 80124c3..579f7d2 100644 --- a/frontend/src/routes/applications/[id]/+page.svelte +++ b/frontend/src/routes/applications/[id]/+page.svelte @@ -38,6 +38,10 @@ type PortSpec = { container: number; expose?: boolean }; let templatePorts = $state([]); let exposed = $state(false); + // Which host interface the published port(s) are bound to. Read back out + // of the stored compose so the form shows what is actually running. + let exposeBind = $state<'loopback' | 'all_interfaces'>('loopback'); + let templateCategory = $state(''); let hostPorts = $state>({}); let exposing = $state(false); @@ -145,10 +149,16 @@ async function loadServiceState() { if (!app?.template_slug) return; try { - const tpl = await api.get<{ ports?: PortSpec[] }>(`/templates/${app.template_slug}`); + const tpl = await api.get<{ ports?: PortSpec[]; category?: string }>( + `/templates/${app.template_slug}` + ); templatePorts = tpl.ports ?? []; - const bindings = parseComposeBindings(app.compose_content ?? ''); + templateCategory = tpl.category ?? ''; + const { bindings, hostIp } = parseComposeBindings(app.compose_content ?? ''); exposed = Object.keys(bindings).length > 0; + // A compose with no interface named predates bind addresses and is + // deployed on loopback, same as the backend's default. + exposeBind = hostIp === '0.0.0.0' ? 'all_interfaces' : 'loopback'; for (const p of templatePorts) { hostPorts[p.container] = bindings[p.container] ?? p.container; } @@ -157,9 +167,15 @@ } } - // Returns { container_port: host_port } from a docker-compose YAML string. - function parseComposeBindings(yaml: string): Record { - const result: Record = {}; + // Reads a docker-compose YAML's `ports:` entries. Accepts both the + // two-part `host:container` form and the three-part + // `host_ip:host:container` form (including a bracketed IPv6 address). + function parseComposeBindings(yaml: string): { + bindings: Record; + hostIp: string | null; + } { + const bindings: Record = {}; + let hostIp: string | null = null; const lines = yaml.split('\n'); let inPorts = false; let portsIndent = -1; @@ -171,9 +187,12 @@ continue; } if (inPorts) { - const portMatch = line.match(/^\s*-\s*"?(\d+):(\d+)"?\s*$/); + const portMatch = line.match( + /^\s*-\s*"?(?:(\[[0-9a-fA-F:]+\]|[0-9.]+):)?(\d+):(\d+)"?\s*$/ + ); if (portMatch) { - result[parseInt(portMatch[2], 10)] = parseInt(portMatch[1], 10); + if (portMatch[1]) hostIp = portMatch[1].replace(/^\[|\]$/g, ''); + bindings[parseInt(portMatch[3], 10)] = parseInt(portMatch[2], 10); continue; } const indent = line.match(/^(\s*)\S/); @@ -182,7 +201,7 @@ } } } - return result; + return { bindings, hostIp }; } async function saveExpose() { @@ -192,7 +211,8 @@ try { await api.put(`/applications/${app.id}/expose`, { expose: exposed, - host_ports: exposed ? hostPorts : {} + host_ports: exposed ? hostPorts : {}, + bind: exposed ? exposeBind : 'loopback' }); toast.success('Service redeploying with new port settings'); await loadApp(); @@ -722,6 +742,51 @@ Ployer Docker network. The container restarts when you save.

{#if exposed} +
+ Reachable from + + +
+ {#if exposeBind === 'all_interfaces'} + + {/if}
{#each templatePorts as p}
@@ -2117,6 +2182,53 @@ .expose-toggle-label input { width: auto; } + .bind-choice { + border: 1px solid var(--border); + border-radius: var(--radius); + padding: 0.6rem 0.85rem; + margin-top: 0.6rem; + display: flex; + flex-direction: column; + gap: 0.5rem; + } + .bind-choice legend { + font-size: 0.8rem; + color: var(--text-muted); + padding: 0 0.3rem; + } + .bind-option { + display: flex; + align-items: flex-start; + gap: 0.5rem; + cursor: pointer; + } + .bind-option input { + width: auto; + margin-top: 0.25rem; + } + .bind-option span { + display: flex; + flex-direction: column; + } + .bind-option strong { + font-weight: 500; + font-size: 0.9rem; + } + .bind-option small { + color: var(--text-muted); + } + .bind-warning { + background: rgba(245, 158, 11, 0.1); + border: 1px solid var(--warning); + color: var(--warning-text); + padding: 0.6rem 0.85rem; + border-radius: var(--radius); + font-size: 0.8125rem; + margin-top: 0.6rem; + } + .bind-warning code { + font-family: monospace; + } .port-rows { display: flex; flex-direction: column; diff --git a/frontend/src/routes/services/[slug]/+page.svelte b/frontend/src/routes/services/[slug]/+page.svelte index 697cfaa..6ee2c24 100644 --- a/frontend/src/routes/services/[slug]/+page.svelte +++ b/frontend/src/routes/services/[slug]/+page.svelte @@ -50,6 +50,10 @@ let values = $state>({}); let showSecrets = $state>({}); let expose = $state(false); + // Which host interface to publish on. Loopback by default: publishing a + // database on every interface puts it on the LAN and on any VPN this host + // has joined, and Docker's port publishing is not filtered by ufw. + let bind = $state<'loopback' | 'all_interfaces'>('loopback'); let hostPorts = $state>({}); let installing = $state(false); @@ -96,7 +100,8 @@ server_id: serverId, inputs: values, expose, - host_ports: expose ? hostPorts : {} + host_ports: expose ? hostPorts : {}, + bind: expose ? bind : 'loopback' }); toast.success('Service installed, deploying...'); } catch (e: any) { @@ -208,10 +213,44 @@ Publish the service port on the host so it's reachable from outside the Ployer - Docker network. Anyone who can reach this server will be able to connect — make - sure your firewall is set up. + Docker network. Other containers on the Ployer network can always reach it + without this. {#if expose} +
+ Reachable from + + +
+ {#if bind === 'all_interfaces'} + + {/if}
{#each template.ports ?? [] as p}
@@ -378,6 +417,50 @@ .expose-toggle input { width: auto; } + .bind-choice { + border: 1px solid var(--border); + border-radius: var(--radius); + padding: 0.6rem 0.85rem; + margin-top: 0.6rem; + display: flex; + flex-direction: column; + gap: 0.5rem; + } + .bind-choice legend { + font-size: 0.8rem; + color: var(--text-muted); + padding: 0 0.3rem; + } + .bind-option { + display: flex; + align-items: flex-start; + gap: 0.5rem; + cursor: pointer; + } + .bind-option input { + width: auto; + margin-top: 0.25rem; + } + .bind-option span { + display: flex; + flex-direction: column; + } + .bind-option strong { + font-weight: 500; + font-size: 0.9rem; + } + .bind-warning { + background: rgba(245, 158, 11, 0.1); + border: 1px solid var(--warning); + color: var(--warning-text); + padding: 0.6rem 0.85rem; + border-radius: var(--radius); + font-size: 0.8125rem; + margin-top: 0.6rem; + } + .bind-warning code { + font-family: monospace; + } .port-rows { display: flex; flex-direction: column;