Adopt a site that is already on your server

Not every site starts in SrvYard. If a server was set up by hand, or by another panel, its sites already exist: files in a folder, an Nginx file, perhaps a Supervisor worker and a cron line. Adopting registers those sites in SrvYard exactly where they are. Nothing is moved, rewritten or restarted. You see the site, its domains, processes and logs, and you decide later, one capability at a time, what SrvYard should take over.

This article follows the path from the read-only scan to a registered site, shows what the Adoption side of a site looks like and how to take over its Nginx file, and explains how to undo the adoption. If you are migrating from another panel in particular, see Migrate from Ploi, VitoDeploy or another panel.

Before you begin#

• A connected server. The scan uses the SSH key SrvYard already has for the server. Add the server first with Connect an existing server. With no ready server the scan page says "No server is ready to scan."
• Owner or admin rights. Taking over a vhost needs the adoption permission, which owners and admins have.
• A recent backup. Adoption starts with a restore point of the web server settings, and everything it does is reversible, but a backup of the sites' databases is cheap insurance.
• About a minute. The scan "usually" finishes within one minute, and its report is kept for 30 days.

1. Start from Import / migrate#

Choose Import / migrate in the sidebar.

1. Import from another panel. For a move from a panel such as Ploi, where SrvYard reads the panel's own data. That route has its own article.
2. Scan a server. The route in this article. The card explains it: SrvYard reads the web server, PHP, Supervisor, cron, databases, certificates and firewall and shows what it found.

2. Choose the server and what the scan may read#

1. Server. The list shows every ready server with its address. The scan "connects with the management key SrvYard already holds", so you do not enter a password.

1. The chosen server. Beside it the form states that private keys, database passwords and password hashes are never read.
2. Start scan. Begins the scan. Cancel goes back.

Next to the server the card What the scan may read lists what is collected. Each row opens an Exact commands list so you can see precisely what runs on your machine.

1. Environment file values (marked sensitive). Off by default. It reads the full content of each .env file, secrets included, so they can be carried to the new setup. They are stored encrypted, separately from the report, and deleted automatically after seven days. Without it, Environment file key names records only the names of the variables and a handful of harmless values such as APP_ENV and DB_HOST.
2. Run php artisan --version (marked sensitive). Off by default. It runs the application's own code once per Laravel site to read the exact framework version. Leave it off unless you trust the code on the server.

The other categories are on by default: server facts, users and SSH access, the web server and PHP configuration, processes and services, background workers and scheduled jobs, databases (metadata only: no passwords, hashes or table content), TLS certificates (metadata only), the firewall, application folders and Git remotes. Anything you leave unticked is not read, and the report shows that part empty. The scan writes nothing, touches no service and installs no package.

3. Read the report and adopt#

When the scan finishes the report lists the sites, workers, scheduled jobs, databases and certificates it found, with warnings for anything unusual. A log shows what the scanner is doing as it runs. From the report you can Download redacted JSON, Scan again or press Adopt this server. A report older than 30 days has expired and the page says so; scan again.

Adoption is a short wizard:

1. Scan. A summary of what adopting does: it checks that the server still looks like the scan and records how every site answers; it takes a restore point, a tarball of the Nginx, PHP-FPM, Supervisor, cron and certbot renewal settings with a manifest and a restore script (the originals are only read); it registers the sites, domains, processes, cron lines, databases, certificates and firewall rules in SrvYard, flagged as adopted; and it checks again that every site answers as before and the configuration is unchanged.
2. Sites. Tick the sites to adopt. Each row shows its layout (Single folder or releases with a current link) and a Confidence. Select all high confidence picks the safe ones; a site that Cannot be adopted says why.
3. User, folder, domains, deploys. Confirm how each site is described. The folder, the user and the layout are what the scan found and are not moved. SrvYard never creates a user: the site Runs as an existing one that owns the folder. You set the PHP version, the Domain name list (primary or alias, with No www redirect, www to apex or apex to www), whether the site deploys with Zero-downtime releases (new releases go into the existing releases folder and the existing current link is switched) or In place, the Repository and Branch (optional: leave the repository empty to deploy by script alone), the Web directory and the Deploy script. The environment file stays on the server and its contents are not read or stored.
4. Processes, cron, data. Processes, scheduled jobs, databases, certificates and firewall rules. They are registered as external: shown in SrvYard with start, stop, restart, logs and run now where that is safe, but never rewritten. The panel's own upkeep cron lines start unticked. Database passwords stay unknown until you reset them.
5. Review the plan. "This is exactly what will be written in SrvYard and exactly what will run on the machine. Nothing has been done yet." It lists every command that will run on the server, in order, and the rows that will be created.
6. Confirm. Tick that you have read the plan and type the server's name to confirm.

The plan is rejected if something is wrong ("Fix this before you adopt"). Fix the choices and review again.

4. What an adopted site looks like#

An adopted site carries an Adopted badge and an extra Adoption tab. Its tabs for logs, commands, processes, domains and the rest work as usual.

The Adoption tab has three parts:

• Nginx vhost. Says who writes the site's Nginx file: Observed only (SrvYard reads it and writes nothing, so domains, redirects, HTTPS and security rules are changed where the file came from), Original text kept (SrvYard writes the same text unchanged) or Managed by SrvYard.
• What works on this site. A list of capabilities, each available or unavailable with a reason until the part of the setup it depends on is SrvYard's: deploy from SrvYard, edit the environment file, add and change domains, issue certificates, edit the Nginx configuration, change the PHP version, Composer and npm credentials, scheduler, Horizon, Octane and Reverb, maintenance mode, reset the Git checkout and delete the site files.
• Where things are. The layout, the user, the home folder, the current release and releases folders, shared files, the environment file, the access and error logs and the PHP-FPM pool (the old one, left alone).

Take over the Nginx file#

Press Take over the vhost. A dialog explains that SrvYard writes the file, reloads Nginx and checks that every domain answers as it does now, and that if anything fails the original is put back by itself. The original file is never deleted.

You choose how:

• Keep the original text writes exactly the same text as SrvYard's own file. Nothing about how the site is served changes. You edit it in the Nginx editor, and domains, redirects and certificates stay in that text.
• Let SrvYard generate it renders SrvYard's vhost from the site, so domains, redirects, HTTPS and security rules work. Directives that existed only in the original are dropped, and the dialog lists the differences before you confirm.

If the file serves other sites as well, the dialog warns you. Put the original vhost back reverses a take-over.

Deploy an adopted site#

SrvYard does not know what your old setup ran, so the first deploy script is only a suggestion: it keeps migrations and the build step commented out until you review it. Read it on the Deployments tab, then deploy. A deployment can be switched off for an adopted site, in which case SrvYard answers "Deploys are turned off for this adopted site."

5. Undo an adoption#

Open the adopted server's page under Import / migrate (the Adopted servers list). It shows each step, a Verification comparing the server with how it looked before, the Restore point (kept on the server for 30 days, with the command to restore it by hand as root) and the log. If a step failed, Continue where it stopped repeats only the steps that did not finish.

Roll back removes what the adoption registered in SrvYard and, if a vhost was taken over, puts the captured files back first. Files on the server that SrvYard never touched are left alone. Detach the old panel shows the guide for switching off the panel that used to manage the server.

Deleting a single adopted site in SrvYard only forgets it: "Nothing on the server is changed or deleted." If SrvYard wrote the Nginx file, that file keeps serving the site.

Troubleshooting#

• "No server is ready to scan." Add the server or wait until it is Ready.
• "This report has expired." Reports are deleted after 30 days. Scan again.
• "The scan failed" or "Some of the server could not be read". A step failed part-way. The log shows which and why. Fix it (for example a permission) and scan again; the sections that worked are still shown.
• A site "Cannot be adopted". Its row gives the reason, such as a layout SrvYard cannot map. Adopt the other sites and handle that one by hand.
• "The server could not build the plan." Check the choices, especially that the user owns the site folder.
• The adoption stopped. Steps that finished are not repeated. Fix the cause and press Continue where it stopped, or Roll back.
• After a take-over a domain stopped answering. SrvYard checks this and restores the original file by itself. If it did not, press Put the original vhost back.

Related#

• Connect an existing server: the server must be connected before it can be scanned.
• Migrate from Ploi, VitoDeploy or another panel: moving from another panel.
• Create a site on your server: the fresh-start alternative.
• Write and test a deploy script: review the suggested script.