Deploy to a hosting account: cPanel, Plesk, DirectAdmin or SFTP
Many apps live on hosting you already pay for: a control panel, no root, no Docker. OpsCrew can deploy to such an account. It sets the app up through the panel’s API from your computer, then deploys each release with a switch in one step, keeps the releases before it for a rollback, and checks the app after every switch. Your app’s secrets stay on the account, outside the web root.
Nothing on the account changes until you approve the exact plan, which OpsCrew shows with its SHA-256 hash first. OpsCrew only ever changes or removes what it made there: an existing site, a database or a mailbox of yours is never touched.
Each panel has its own page, with the variables to set and its limits:
This page is what they share. An account on a panel is called a panel account below; an SFTP host works differently, as its page says.
What fits
Section titled “What fits”A hosting account runs code only while it answers a request. It fits:
- static sites, including those your build makes;
- PHP apps: plain PHP and Laravel, with a MySQL or MariaDB database;
- a PostgreSQL database on a cPanel account whose host installed PostgreSQL (see PostgreSQL on cPanel; not tested on a real account yet);
- a Laravel queue on the database connection: its worker runs from cron every minute until the queue is empty, so a queued job starts within about a minute;
- Node.js and Python apps, on a panel account whose panel runs them (CloudLinux’s selector), while it has an app slot left.
npx opscrew design refuses an app that needs more, says why and names a server target instead:
- a worker that keeps running, or a queue OpsCrew would run for the app (Redis, RabbitMQ);
- Redis, or any service that runs only in a container (keep a hosted one with
keepExternalServicesinopscrew interview); - WebSockets from PHP;
- PostgreSQL on Plesk and DirectAdmin, and on a cPanel account whose host didn’t install it;
- an app larger than the disk the account has left.
The PHP version and its extensions are read on the account at provision; see The PHP version.
What you need
Section titled “What you need”- The variables of your panel, or of your SFTP host, in your shell (see the panel’s page).
npx opscrew initchecks them; nothing is sent anywhere then. - A GitHub repository with your app, and
GITHUB_TOKENas for every OpsCrew deployment (see The GitHub token). On a panel account it also needs Administration: Read and write, for the agent’s deploy key. CLOUDFLARE_API_TOKENonly when the hostname’s DNS is on Cloudflare: OpsCrew then adds its A record to the account’s address, DNS only, through its own approval.
Then run the usual steps:
npx opscrew interview # choose "A hosting account"; OpsCrew finds the panel and asks the hostnamenpx opscrew design # what the account offers and what the app gets therenpx opscrew provision # the plans, each approved by its hashThe interview offers a hosting account only while your panel’s or your SFTP host’s variables are set. It finds which panel answers by itself, and asks for the hostname: a new subdomain of one of the account’s domains, or a domain of yours the account doesn’t serve yet (added to the account as a new domain). OpsCrew never takes over a hostname that exists. Design shows the web server (Apache or LiteSpeed), the database engine, the disk left and the app slots left, and no price: you already pay for the account.
How a deploy works
Section titled “How a deploy works”On a panel account, a small deploy script, the agent, runs on the account itself. Cron starts
it every minute as the account’s user, with this cron line (its output goes to state/agent.log in
the same folder):
* * * * * /bin/bash "$HOME/opscrew/<app>-<env>/agent.sh" >> …/state/agent.log 2>&1When you push to the deploy branch:
- GitHub Actions builds the release: Composer’s packages, the assets, a static site’s build.
- It publishes the release on the branch
opscrew/release/<env>of your repository, signed with the release signing key, a secret of the deploy environment (OPSCREW_RELEASE_SIGNING_KEY). - The agent fetches it within the minute, with a read-only deploy key it made itself on the account, and checks the signature with the key’s public half. A release that isn’t signed by that key, or one older than the last it tried, is refused and never deployed.
- It prepares the release in a folder of its own, runs the release command (Laravel’s migrations, for example) with the hostname’s PHP, then switches the hostname to it with one rename.
- It checks the app over HTTPS until it answers with the new release (the
X-OpsCrew-Releaseheader). When it doesn’t, the agent switches back. A failed release command leaves the running release untouched. - The workflow waits until the account serves the release, up to 10 minutes. When it doesn’t,
the run fails and says to run
npx opscrew status --env <env>, which shows why.
A release goes live about a minute after its build. The agent keeps the 3 releases before the running one for a rollback.
On a panel account, no credential for the account is ever in GitHub. GitHub holds only the key that signs releases; the account holds its public half, so nothing on the account can sign one. Whoever can run the deploy environment’s workflow can deploy, as on a server. A pull request’s workflow can’t sign a release where GitHub limits the environment’s secrets to the deploy branch; where GitHub can’t (a private repository on GitHub Free), OpsCrew says so before the signing key’s own approval.
The release branch
Section titled “The release branch”opscrew/release/<env> holds one commit: the built release, without the .git, .github,
node_modules and opscrew folders. Each deploy replaces it with a force-push, so the branch has
no history. Leave it alone: it is how the agent gets each release, and npx opscrew destroy
removes it.
On the account
Section titled “On the account”Everything OpsCrew puts on the account is in ~/opscrew/<app>-<env>/:
| Path | What it is |
|---|---|
agent.sh, settings.sh |
The agent and its settings, copies of opscrew/hosting/agent.sh and opscrew/hosting/<env>.sh in your repository |
releases/ |
The running release and the 3 before it |
current |
The link to the running release; the hostname serves it |
app/ |
A Node.js or Python app’s root in CloudLinux’s selector, whose packages every release runs with; the app runs current/<startup file> from it, through its link app/current to the running release: don’t remove it by hand while the app exists |
shared/ |
The app’s settings (.env, 0600), the database’s login for its dumps, Laravel’s storage and the app’s kept folders (storage.files.dir, storage.sqlite.dir in opscrew/plan.yaml), linked into each release so what the app writes there outlives it |
dumps/ |
The database dumps and snapshots |
state/ |
The agent’s status, its log (its last 1,000 lines) and the app’s cron output |
The hostname’s document root is the running release’s folder itself, where the panel allows a
document root outside public_html. Otherwise it is a link in public_html (cPanel) or the folder
the panel made for the hostname (DirectAdmin), pointing at the release. Such a folder can be
reached through the main domain too, which OpsCrew’s .htaccess rules refuse: they answer only the
app’s hostname.
The panel’s token
Section titled “The panel’s token”On a panel account, OpsCrew reads the panel’s token from OPSCREW_HOSTING_TOKEN on your computer,
and uses it there only. It is never written to the plan, a file, a log or GitHub. The panel and
the user are saved in .opscrew/hosting.json, on your computer.
A cPanel API token reaches the whole account: every site, database and mailbox on it. cPanel can’t limit a token to some features or addresses: it drops such limits and keeps the token’s full access. Keep it in your shell’s environment only, give it an expiry date in cPanel, and revoke it in cPanel (Security → Manage API Tokens) when you no longer run OpsCrew’s commands. Deploys don’t need it: the agent deploys without it.
Provision: two plans
Section titled “Provision: two plans”npx opscrew provision shows and applies two plans on a panel account, each approved by its own
hash:
- Plan A, the agent: the app’s folder with the agent, its settings and GitHub’s host keys, then the agent’s cron line. OpsCrew then waits up to 3 minutes for the agent’s first report: the PHP versions and extensions on the account, its tools, whether it reaches GitHub, and its deploy key.
- Plan B, the app, built from that report: a new release signing key (its private half goes to GitHub, its public half to the account), the database and its user (the password generated then, kept only in the app’s settings on the account), the app’s settings, the hostname with its document root and its PHP version, the app’s cron jobs, and the certificate.
When the report shows the account can’t run the app, provision stops after plan A with the reason
and what to do; npx opscrew destroy removes the agent.
Before plan B, the DNS record on Cloudflare gets its own approval. While plan B applies, the signing key’s private half goes to GitHub after its own approval. Then the agent’s deploy key on GitHub and the deploy workflow in the provision pull request, each with its own approval.
The values of your app’s settings never appear in a plan: it lists their names and a digest. Where the panel’s API can’t make something, the plan lists it as a step for you to do in the panel, with the exact values; provision stops there, and running it again continues once you have done it.
On cPanel (AutoSSL) and DirectAdmin the panel issues the hostname’s free certificate by itself; provision waits up to 5 minutes for it and says why when it doesn’t come. On Plesk the certificate is yours (see Plesk). Until the agent sees a valid certificate, the app answers over HTTP; then OpsCrew’s rules redirect HTTP to HTTPS.
The PHP version
Section titled “The PHP version”Design reads what your app needs from composer.json and composer.lock: its PHP version and
extensions. At provision, the agent’s report says what the account has, and plan B picks the
first that fits:
- the account’s own PHP version;
- a version for this hostname alone, set through the panel: cPanel’s MultiPHP sets it; on Plesk and DirectAdmin it is a step for you in the panel;
- on a CloudLinux account served by LiteSpeed, another version for this hostname through a handler
line in its
.htaccess, when that version’s default extensions cover the app. Only the default extensions load that way: nombstring,fileinfo,intlorgd, for example.
When none fits, provision stops before it makes the hostname or the database, and names what the
app needs and what the account has. OpsCrew never changes the account’s PHP version: every site
on the account shares it, and a change could break the others. You can change it yourself in the
panel’s PHP selector (every site on the account changes with it), or ask your host for PHP per site
(CloudLinux Isolates); then run npx opscrew provision again.
The release command and the app’s cron jobs run with the chosen version’s PHP, never with the PHP
cron finds first. npx opscrew verify checks the version the app answers with.
LiteSpeed and Apache
Section titled “LiteSpeed and Apache”Design says which web server serves the account. OpsCrew’s .htaccess rules work the same on both.
After a PHP app’s switch, the agent makes PHP serve the new release:
- On LiteSpeed, it restarts the account’s PHP processes and empties LiteSpeed’s page cache. The restart reaches every PHP process of the account, other sites’ included, for a moment: LiteSpeed has no narrower restart for an account’s user. It happens on every deploy and rollback of a PHP app; a static site’s switch restarts nothing.
- On Apache with PHP-FPM, an account’s user can’t restart PHP, so some requests may still run
the release before for about 2 minutes after a deploy or a rollback. OpsCrew turns on
opcache.revalidate_pathin each PHP release’s.user.iniand.htaccess, so PHP’s code cache follows the switch once PHP’s path cache expires (realpath_cache_ttl, 120 seconds). The agent’s check waits that long before it counts, andnpx opscrew statussays so.
Your app’s settings
Section titled “Your app’s settings”Your app’s values and the database’s password go from your computer to 0600 files in
~/opscrew/<app>-<env>/shared/, outside every web root. GitHub never gets them. Laravel reads its
.env; a plain PHP app reads them through getenv(), $_ENV and $_SERVER, which OpsCrew’s
env.php fills before the app runs.
To change a value, run npx opscrew provision again: the plan lists the settings’ names and a new
digest; nothing else changes. The agent puts the new settings in place.
OpsCrew’s .htaccess block comes first in each release’s .htaccess; what the panel wrote there
and your app’s own .htaccess follow it, unchanged. The block turns directory listings off, refuses
dotfiles and every other hostname, redirects to HTTPS once there is a certificate, and sets the
security headers.
When your PHP app has an index.php but no rewrite rules of its own in .htaccess, the block
also sends every path that isn’t a file or folder to that index.php, as a server does.
Status, logs and checks
Section titled “Status, logs and checks”npx opscrew statusshows what the agent last did; see What each target can’t give.npx opscrew logsshows the agent’s last lines; see Your app’s logs.npx opscrew verifychecks that the app answers over HTTPS with the release, that HTTP redirects, and that its settings,.htaccess, the release folders and Composer’s packages can’t be read from the web.npx opscrew securechecks the PHP version against PHP’s supported versions, that the settings are outside the web root, OpsCrew’s.htaccessrules and HTTPS. The account itself is your host’s to secure: OpsCrew has no SSH, firewall or kernel there to check.npx opscrew driftreports what changed in the panel since provision: the document root, the database, the cron jobs, the agent and its settings, and the deploy key on GitHub.
Snapshots
Section titled “Snapshots”npx opscrew snapshot and npx opscrew restore <id> work through the agent. Snapshots stay on
the account, in ~/opscrew/<app>-<env>/dumps/; how to keep a copy elsewhere is in
On a hosting account. With deploy.snapshots on (the
default), the agent also dumps the database before each release, and keeps the dumps of the
releases it keeps.
Restore drills
Section titled “Restore drills”npx opscrew restore --drill proves a snapshot restores (see
Restore drills for what every drill shares). An account has one
site per folder and hostname and no way to cut a second copy of the app off from the outside, so a
drill here proves less than on a server: the dump loads into an empty database and holds its
tables; the app isn’t started. Whether the app runs on that data is not checked.
The drill database
Section titled “The drill database”Drills load the dump into a database of their own, never the app’s. Turn them on with
drills: {} under snapshots: in opscrew/plan.yaml (or with
npx opscrew snapshot drill schedule on), then run npx opscrew provision: plan B makes the
drill database, named after the app’s with _drill at the end, and its own user, which has no
right on the app’s database. Each drill empties that database, so you approve the plan by its hash
with <app>-drill typed. Its password is generated then and kept only in
~/opscrew/<app>-<env>/keys/drill.cnf (keys/drill.pgpass for PostgreSQL; 0600, outside every
web root). It is one more database on the account, so it counts against your hosting plan’s
limit on databases: check there is room for it before you turn drills on. Removing
snapshots.drills and running provision removes it, and so does npx opscrew destroy.
A drill
Section titled “A drill”The agent runs it under its lock, between releases, signed in with the drill database’s own
login, after you approve its request by typing <app>-drill. By default it takes the newest
snapshot you took with npx opscrew snapshot; name another by its id. It:
- checks the dump is a valid gzip file and not empty;
- drops every table and view in the drill database, then loads the dump into it, with its
DEFINER=clauses left out, so its views and triggers are made with the drill’s own user; - counts the drill database’s tables against the dump’s
CREATE TABLElines (names and counts only: no row is read); - empties the drill database again, so no copy of the data stays beyond the dump itself;
- lists the snapshot’s copy of the shared files as an archive; nothing is unpacked.
A drill takes 30 minutes at most: then it is stopped, the drill database emptied and the drill
recorded as failed. --keep, --remove, --only and --allow-other-version don’t apply here.
On a schedule
Section titled “On a schedule”With npx opscrew snapshot drill schedule on (--every daily for daily drills), the next
npx opscrew provision puts the schedule in the agent’s settings, in a plan approved the same way
(see On a schedule). The account takes no snapshot on a schedule, so
the agent drills the newest snapshot you took, once no drill has proved it yet (a skip doesn’t
count). Its slot is a server’s: weekly on Thursdays from 03:00 UTC, or daily from 03:00 UTC, one
run per slot, after the releases under the agent’s lock, so never during a deploy, and with no
call to the panel. It keeps
a drill by hand’s bounds, and is skipped, recorded and never a failure, when there is no snapshot
yet, when the drill database’s login isn’t there yet, or when the room the account’s disk quota
leaves is smaller than the dump. That quota is the account’s file quota, which on many hosts
doesn’t count the space its databases use, so the check can pass while the database server
itself has no room left.
The agent runs as the account’s user, so anything that user can run, the app’s own code included, can go past these bounds.
Each drill leaves one line, with no value in it, in ~/opscrew/<app>-<env>/state/drills.log,
which npx opscrew status reads.
Rolling back
Section titled “Rolling back”npx opscrew rollback --list # the releases the account keepsnpx opscrew rollback # back to the release before the running onenpx opscrew rollback --to <release> # back to a kept release, such as 1234567890-1The agent switches back in one step, and on LiteSpeed restarts PHP as after a deploy. Nothing is
rebuilt, and the release command doesn’t run. For the database you choose between restoring the
dump taken when that release stopped running and keeping it as it is (--database snapshot or
--database keep); outside prod the dump is the default, on prod keeping it. Restoring needs the
hostname typed. Then deploys pause, as on a server; see
Deploys pause after a rollback.
Removing the app
Section titled “Removing the app”npx opscrew destroy shows a plan of what OpsCrew made, and nothing else, and needs the hostname
typed:
- a final dump of the database, offered first and kept in the app’s
dumps/folder (with--no-snapshot, none); - the cron lines OpsCrew made, the agent’s first;
- the hostname, and its link in
public_htmlwhen there is one; - the certificate issued for the hostname, when nothing else uses it;
- the database and its user, and the drill database and its user;
- the app’s folder (but the final dump), and
~/opscrewwhen it is empty; - the DNS record on Cloudflare; on GitHub, the deploy key, the signing key and the release branch.
Commands that need a server
Section titled “Commands that need a server”opscrew vpn, opscrew runner, opscrew portainer, the add-ons (Beszel, monitoring),
previews and opscrew retarget need a server, and say so on a hosting account with
what to use instead. To move the app to a server, see
What can’t move yet.
If you stop using OpsCrew
Section titled “If you stop using OpsCrew”Your deployment keeps working. The agent and its cron line stay on the account, and the workflow
and the signing key stay in GitHub, so each push still deploys. The agent is a plain bash script
you can read in your repository (opscrew/hosting/agent.sh). To stop it, remove its cron line in
the panel; remove ~/opscrew/<app>-<env>/ there too when you no longer want the releases.