Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 96 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
name: CI

on:
push:
branches:
- main
pull_request:

permissions:
contents: read

concurrency:
group: ci-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

env:
CARGO_TERM_COLOR: always
# Required: `.cargo/config.toml` points DATABASE_URL at
# sqlite://ployer.db?mode=rwc, which would CREATE an empty database here and
# make every sqlx::query! macro fail with "no such table". Offline mode uses
# the committed .sqlx/ metadata instead. See DOCUMENTATION.md > Prerequisites.
SQLX_OFFLINE: true

jobs:
# The lint gate runs on a PINNED toolchain, on purpose.
#
# `-D warnings` plus a floating `stable` means every six-week Rust release can
# red-light every open PR over a brand-new lint that has nothing to do with the
# change under review. Pinning makes the gate deterministic: a clippy upgrade
# becomes its own PR that bumps this version and fixes the new findings in one
# place, reviewed on its own merits.
#
# To upgrade: bump the version below, run
# cargo +<version> clippy --workspace --all-targets -- -D warnings
# locally, fix what it finds, and ship both together.
lint:
name: Clippy (pinned 1.99.1)
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- name: Install Rust toolchain
uses: dtolnay/rust-toolchain@master
with:
toolchain: 1.99.1
components: clippy, rustfmt

# reqwest is built with its default native-tls feature, so openssl-sys
# needs system OpenSSL or the build fails on the first dependency.
- name: Install build dependencies
run: |
sudo apt-get update -qq
sudo apt-get install -y libssl-dev pkg-config

- name: Cache Rust dependencies
uses: Swatinem/rust-cache@v2
with:
key: lint-1.99.1

# The gate. Any warning is an error; see DOCUMENTATION.md >
# Development Checks for how to handle a lint that is wrong for a
# specific call site.
- name: cargo clippy -- -D warnings
run: cargo clippy --workspace --all-targets -- -D warnings

# Not a gate: the tree has ~325 unformatted hunks and a blanket reformat
# is a separate decision. GitHub reports a continue-on-error step as
# green whatever happens, so this is log-only visibility, not a signal.
- name: cargo fmt (advisory, non-blocking)
continue-on-error: true
run: cargo fmt --all -- --check

# Tests run on floating `stable` so genuine compiler and runtime regressions
# still surface; a test failure is always worth looking at, whereas a new lint
# usually is not urgent.
test:
name: Tests (stable)
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- name: Install Rust toolchain
uses: dtolnay/rust-toolchain@stable

- name: Install build dependencies
run: |
sudo apt-get update -qq
sudo apt-get install -y libssl-dev pkg-config

- name: Cache Rust dependencies
uses: Swatinem/rust-cache@v2
with:
key: test-stable

- name: cargo test
run: cargo test --workspace
67 changes: 67 additions & 0 deletions DOCUMENTATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,53 @@
- **Rust** (1.75+) — [rustup.rs](https://rustup.rs)
- **Node.js** (20+) or **Bun** (1.0+) — for frontend builds
- **Docker** (optional) — required for container management features
- **OpenSSL headers** — `libssl-dev` on Debian/Ubuntu, `openssl-devel` on
Fedora/RHEL, `openssl` on macOS (Homebrew). Required: `reqwest` is built with
its default `native-tls` feature, so `openssl-sys` must find system OpenSSL
or the build fails on the very first dependency, long before any Ployer code
is reached.

```bash
sudo apt-get install -y libssl-dev pkg-config # Debian / Ubuntu
```

The failure looks like this, and it is not a Ployer bug:

```
error: failed to run custom build command for `openssl-sys v0.9.x`
Could not find directory of OpenSSL installation
```

### `SQLX_OFFLINE=true` is required for every cargo command

Ployer uses `sqlx`'s compile-time-checked `query!` macros, which need either a
live database matching the schema or the checked-in offline metadata in
`.sqlx/`. Always build and test with:

```bash
export SQLX_OFFLINE=true
```

Without it, `.cargo/config.toml` points `DATABASE_URL` at
`sqlite://ployer.db?mode=rwc`, whose `mode=rwc` *creates* an empty database in
whatever directory you happen to be in. The macros then type-check against that
empty database and every one of them fails:

```
error: error returned from database: (code: 1) no such table: applications
```

The fix is never "run the migrations" — it is to set `SQLX_OFFLINE=true` and
use the committed `.sqlx/` metadata. Only regenerate that metadata
(`cargo sqlx prepare --workspace`, against a migrated database) when you change
a SQL query.

## Quick Start

### 1. Build the backend

```bash
export SQLX_OFFLINE=true
cargo build --workspace
```

Expand Down Expand Up @@ -52,6 +93,32 @@ Expected response:

`docker: false` is normal if Docker is not running.

## Development Checks

CI (`.github/workflows/ci.yml`) runs these on every push and pull request, and
they are the same commands to run locally before opening a PR:

```bash
export SQLX_OFFLINE=true
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
```

The clippy gate is enforced: **any** warning fails the build. If you are adding
a function that trips a lint you believe is wrong for the case at hand, add a
narrowly scoped `#[allow(clippy::the_lint)]` on that item with a comment saying
why, rather than widening the gate or silencing the lint crate-wide. There are
currently six such allows, all `clippy::too_many_arguments` on SQL writers whose
arguments are one-per-column.

`cargo fmt --check` is **not** a gate: the tree predates any formatting
discipline and currently has ~325 unformatted hunks spread across nearly every
file, so turning it on would either fail immediately or require a tree-wide
reformat that would bury every subsequent `git blame`. That is its own
decision, not a side effect of a lint cleanup. CI still runs it as a
`continue-on-error` step, so the current state is one click away in the job
log; note that GitHub reports such a step as green regardless of its result.

## CLI Commands

| Command | Description |
Expand Down
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,8 @@ A lightweight, self-hosted PaaS — deploy your apps from Git with automatic SSL

> **Important:** Install on a **fresh, dedicated server**. Ployer owns ports 80 and 443 via Caddy. It will conflict with Nginx, Apache, Coolify, or any other reverse proxy already running on those ports.

**Building from source?** You need `libssl-dev` and `SQLX_OFFLINE=true` as well — see [DOCUMENTATION.md § Prerequisites](DOCUMENTATION.md#prerequisites). The above applies to *running* a release binary.

---

## Quick Install
Expand Down
6 changes: 5 additions & 1 deletion crates/ployer-api/src/routes/domains.rs
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,11 @@ async fn add_domain(
let repo = DomainRepository::new(state.db.clone());

// Check if domain already exists
if let Some(_) = repo.find_by_domain(&domain_name).await.map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))? {
let existing = repo
.find_by_domain(&domain_name)
.await
.map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
if existing.is_some() {
return Err((StatusCode::CONFLICT, "Domain already exists".to_string()));
}

Expand Down
5 changes: 4 additions & 1 deletion crates/ployer-api/src/routes/system.rs
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,10 @@ async fn fetch_latest_version() -> Option<String> {
.map(|t| (t.to_string(), r))
})
.collect();
candidates.sort_by(|a, b| version_key(&b.0).cmp(&version_key(&a.0)));
// `sort_by_cached_key` rather than `sort_by_key`: `version_key` allocates a
// Vec<(u32, String)> per call, and a plain comparator recomputes it twice per
// comparison. Caching makes it one key per element.
candidates.sort_by_cached_key(|c| std::cmp::Reverse(version_key(&c.0)));

let latest_tag = candidates
.into_iter()
Expand Down
11 changes: 8 additions & 3 deletions crates/ployer-api/src/services/deployment.rs
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,11 @@ impl DeploymentService {
}

/// Execute the full deployment pipeline
// spawned as a detached task, so every dependency must be passed by value rather than
// borrowed from AppState; the first six are the ambient services and the last four are this
// job's inputs. Bundling them into a struct is a refactor of the deployment hot path,
// deliberately not folded into a lint fix.
#[allow(clippy::too_many_arguments)]
async fn execute_deployment(
db: SqlitePool,
docker: Arc<DockerClient>,
Expand Down Expand Up @@ -226,9 +231,9 @@ impl DeploymentService {
}

// Also force-remove by fixed name (catches untracked containers with the same name)
match docker.remove_container(&container_name, true).await {
Ok(_) => send_log(format!("Removed existing container '{}'", container_name)).await,
Err(_) => {} // doesn't exist — that's fine
// An Err here just means no such container, which is the normal case.
if docker.remove_container(&container_name, true).await.is_ok() {
send_log(format!("Removed existing container '{}'", container_name)).await;
}

// Note: we no longer kill "containers bound to this port" — app containers
Expand Down
31 changes: 22 additions & 9 deletions crates/ployer-core/src/models/application.rs
Original file line number Diff line number Diff line change
Expand Up @@ -23,20 +23,15 @@ pub struct Application {
pub updated_at: DateTime<Utc>,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
#[serde(rename_all = "snake_case")]
pub enum BuildStrategy {
#[default]
Dockerfile,
Nixpacks,
DockerCompose,
}

impl Default for BuildStrategy {
fn default() -> Self {
BuildStrategy::Dockerfile
}
}

impl BuildStrategy {
pub fn as_str(&self) -> &str {
match self {
Expand All @@ -46,7 +41,16 @@ impl BuildStrategy {
}
}

pub fn from_str(s: &str) -> Self {
/// Parse a `BuildStrategy` out of the string stored in its database column.
///
/// Total and lossy by design: an unrecognised value yields
/// [`BuildStrategy::Dockerfile`] rather than an error, so a row written by a newer
/// schema can never make an existing row unreadable.
///
/// Deliberately not [`std::str::FromStr`]: that trait would need
/// `Err = Infallible`, which hides the fallback from callers and makes
/// `"nonsense".parse()` look like a successful parse.
pub fn from_db_str(s: &str) -> Self {
match s {
"dockerfile" => BuildStrategy::Dockerfile,
"nixpacks" => BuildStrategy::Nixpacks,
Expand Down Expand Up @@ -77,7 +81,16 @@ impl AppStatus {
}
}

pub fn from_str(s: &str) -> Self {
/// Parse a `AppStatus` out of the string stored in its database column.
///
/// Total and lossy by design: an unrecognised value yields
/// [`AppStatus::Idle`] rather than an error, so a row written by a newer
/// schema can never make an existing row unreadable.
///
/// Deliberately not [`std::str::FromStr`]: that trait would need
/// `Err = Infallible`, which hides the fallback from callers and makes
/// `"nonsense".parse()` look like a successful parse.
pub fn from_db_str(s: &str) -> Self {
match s {
"idle" => AppStatus::Idle,
"building" => AppStatus::Building,
Expand Down
8 changes: 4 additions & 4 deletions crates/ployer-core/src/models/application_tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,13 @@ fn build_strategy_round_trips() {
(BuildStrategy::DockerCompose, "docker_compose"),
] {
assert_eq!(variant.as_str(), s);
assert_eq!(BuildStrategy::from_str(s), variant);
assert_eq!(BuildStrategy::from_db_str(s), variant);
}
}

#[test]
fn build_strategy_unknown_defaults_to_dockerfile() {
assert_eq!(BuildStrategy::from_str("unknown"), BuildStrategy::Dockerfile);
assert_eq!(BuildStrategy::from_db_str("unknown"), BuildStrategy::Dockerfile);
}

#[test]
Expand All @@ -27,13 +27,13 @@ fn app_status_round_trips() {
(AppStatus::Failed, "failed"),
] {
assert_eq!(variant.as_str(), s);
assert_eq!(AppStatus::from_str(s), variant);
assert_eq!(AppStatus::from_db_str(s), variant);
}
}

#[test]
fn app_status_unknown_defaults_to_idle() {
assert_eq!(AppStatus::from_str("mystery"), AppStatus::Idle);
assert_eq!(AppStatus::from_db_str("mystery"), AppStatus::Idle);
}

#[test]
Expand Down
22 changes: 20 additions & 2 deletions crates/ployer-core/src/models/deployment.rs
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,16 @@ impl DeploymentStatus {
}
}

pub fn from_str(s: &str) -> Self {
/// Parse a `DeploymentStatus` out of the string stored in its database column.
///
/// Total and lossy by design: an unrecognised value yields
/// [`DeploymentStatus::Queued`] rather than an error, so a row written by a newer
/// schema can never make an existing row unreadable.
///
/// Deliberately not [`std::str::FromStr`]: that trait would need
/// `Err = Infallible`, which hides the fallback from callers and makes
/// `"nonsense".parse()` look like a successful parse.
pub fn from_db_str(s: &str) -> Self {
match s {
"queued" => DeploymentStatus::Queued,
"cloning" => DeploymentStatus::Cloning,
Expand Down Expand Up @@ -103,7 +112,16 @@ impl HealthCheckStatus {
}
}

pub fn from_str(s: &str) -> Self {
/// Parse a `HealthCheckStatus` out of the string stored in its database column.
///
/// Total and lossy by design: an unrecognised value yields
/// [`HealthCheckStatus::Unknown`] rather than an error, so a row written by a newer
/// schema can never make an existing row unreadable.
///
/// Deliberately not [`std::str::FromStr`]: that trait would need
/// `Err = Infallible`, which hides the fallback from callers and makes
/// `"nonsense".parse()` look like a successful parse.
pub fn from_db_str(s: &str) -> Self {
match s {
"healthy" => HealthCheckStatus::Healthy,
"unhealthy" => HealthCheckStatus::Unhealthy,
Expand Down
8 changes: 4 additions & 4 deletions crates/ployer-core/src/models/deployment_tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,13 @@ fn deployment_status_round_trips() {
(DeploymentStatus::RolledBack, "rolled_back"),
] {
assert_eq!(variant.as_str(), s);
assert_eq!(DeploymentStatus::from_str(s), variant);
assert_eq!(DeploymentStatus::from_db_str(s), variant);
}
}

#[test]
fn deployment_status_unknown_defaults_to_queued() {
assert_eq!(DeploymentStatus::from_str("unknown"), DeploymentStatus::Queued);
assert_eq!(DeploymentStatus::from_db_str("unknown"), DeploymentStatus::Queued);
}

#[test]
Expand All @@ -30,11 +30,11 @@ fn health_check_status_round_trips() {
(HealthCheckStatus::Unknown, "unknown"),
] {
assert_eq!(variant.as_str(), s);
assert_eq!(HealthCheckStatus::from_str(s), variant);
assert_eq!(HealthCheckStatus::from_db_str(s), variant);
}
}

#[test]
fn health_check_status_unknown_defaults_to_unknown() {
assert_eq!(HealthCheckStatus::from_str("bad"), HealthCheckStatus::Unknown);
assert_eq!(HealthCheckStatus::from_db_str("bad"), HealthCheckStatus::Unknown);
}
Loading
Loading