Import servers from Laravel Forge or Ploi

The import brings servers you manage with Laravel Forge or Ploi over to Vimonto Deploy, with their sites, processes, cron jobs, databases and firewall rules. It takes each server over in place: nothing is reinstalled, your domains keep pointing at the same machines, and the sites keep running while they move.

You give Vimonto Deploy an API token of the platform, pick the servers, and each server is taken over in a task of its own. When it is done, the server is managed in Vimonto Deploy like any other, and you archive it in Forge or Ploi.

Before you start#

• Permission. Importing needs permission to create servers: the Owner, Administrator or Manager role.
• Room in your plan. Every imported server and every site on it counts towards your plan. The page checks that the servers and sites you picked fit before it starts, and each server checks again when its task runs. On the free plan (1 server and 3 sites) that is one server with up to three sites; for more, upgrade first.
• An API token of the platform, with the rights described below.
• Your SSH key (recommended). Add your public key under Account → SSH keys so you can still log in yourself; see SSH keys.

Create the API token#

The page links to the right place for the platform you choose:

• Laravel Forge: create a token at forge.laravel.com/profile/api. Vimonto Deploy uses Forge's organization API, and lists the servers of every Forge organization the token can see. The token must be allowed to read servers and sites (including the environment file and deploy script), to create and run recipes, and to switch off push to deploy.
• Ploi: create an API key at ploi.io/profile/api-keys. It must be allowed to read servers and sites (including the environment file and deploy script), to create and run scripts, and to switch off quick deploy.

The token is only used to read your servers and to run one script that gives Vimonto Deploy access. It is stored encrypted, and erased as soon as every server of that account is imported (or already in your organization). Use another account also erases it.

If the platform refuses the token, the page says so under the field: … refused the API token, The … token is missing a permission this needs or … is limiting requests; try again in a minute.

Import servers step by step#

1. Go to Servers, open the arrow next to New server and choose Import from Forge or Ploi. The page Import servers opens.
2. Under Where are your servers now?, choose Laravel Forge or Ploi.
3. Paste the token under API token and click Read my servers. Nothing changes on your servers yet: Vimonto Deploy only reads the account.
4. The panel Servers in Laravel Forge (or Servers in Ploi) lists every server with its IP address, PHP version, database, Ubuntu version and the domains of its sites. Servers whose IP address is already in your organization show Already here and cannot be picked; the others show Ready to import and are all ticked. Untick the ones you want to leave.
5. Read the note next to the button, then click Import :count servers (for example Import 2 servers).

Each server becomes a task of its own, called Import … from …. Its status changes to Queued, then Importing, then Imported or Failed. Below each server, the page shows the step it is on and, as it goes, a report of what was done and anything that needs your attention. You can close the page: the tasks keep running, you get a message in whatever tab you have open when each ends, and they are on the activity page with their full output.

What happens to each server?#

The task has six steps.

1. Read the server and its sites#

Vimonto Deploy reads everything the platform knows about the server: its sites, background processes and queue workers, cron jobs, databases, database users and firewall rules. Anything the platform sends that cannot be used safely (for example an invalid domain, directory or user name) is left out, and the report says … was not imported: the platform sent settings for it that can't be used safely.

2. Add the server here#

The server is added to your organization as an App server with its name, public and private IP address, PHP version, database and Ubuntu version. It gets an SSH key pair of its own, like every server in Vimonto Deploy. It is not linked to a cloud account: it is managed like a custom VPS.

3. Get access to the server#

Through the platform, Vimonto Deploy runs one script as root on that server: a recipe in Forge, a script in Ploi. The script adds the server's new public key to /root/.ssh/authorized_keys. If SSH was set to PermitRootLogin no, it changes that to prohibit-password, so root can log in with a key, never with a password. Vimonto Deploy then waits up to 5 minutes for SSH to let it in.

It then looks at the machine itself: the Ubuntu version, the installed PHP versions, the Supervisor programs, and for every site whether its directory exists, whether it is a Laravel app, and whether it runs in place or from releases. The PHP versions it finds appear on the server's PHP page, and SSH, HTTP and HTTPS appear as the server's standard firewall rules.

4. Take over processes and cron jobs#

• Databases and firewall rules are recorded as they are: the databases, the database users and which databases they can use, and the firewall rules beyond SSH, HTTP and HTTPS. Nothing about them changes on the server.
• Supervisor programs: every program that is not Vimonto Deploy's own moves from /etc/supervisor/conf.d to /root/vimonto-takeover-backup/supervisor, and Vimonto Deploy writes its own processes from what the platform reported. The report lists the programs it moved.
• Cron jobs: a copy of the system user's and root's crontab goes to /root/vimonto-takeover-backup/cron, and the lines that run one of the platform's cron jobs are taken out; the rest of each crontab stays. The same happens in /etc/crontab (copied first), and files in /etc/cron.d that run one of the platform's jobs move to the backup folder. Vimonto Deploy writes the jobs again as scheduled jobs.

Queue workers that belong to a site, and cron jobs that run a site's schedule:run, are not made here: they move with their site in the next step.

5. Move the sites over#

Each site is moved one by one. A site that cannot be moved does not stop the others: the report says … was not moved: with the reason, for example when its directory is not on the server.

For every site:

1. The site is added with its domain and aliases, directory, web directory, PHP version, repository and branch, and its framework (Laravel, Statamic, WordPress, Symfony, static HTML, Nuxt, Next.js or plain PHP). A site that ran as its own Linux user stays isolated under that user. The .env is read from the platform. No new deploy key is added: the server keeps the Git access the platform set up.
2. The deploy script is translated by Vimonto Deploy: lines that cd into the site or run git pull, fetch, reset, checkout or clean go (every deploy here starts from a fresh checkout), Forge's and Ploi's variables become Vimonto Deploy's ($FORGE_SITE_PATH and {SITE_DIRECTORY} become $VIMONTO_RELEASE_PATH, and so on), Forge's release commands are left out, and the PHP-FPM reload goes, because every deploy reloads PHP-FPM by itself. If a platform variable is left over, the report says The deploy script still uses …; check it under Deployments. See the deploy script variables.
3. The live certificate is carried over: the certificate and key the platform's Nginx config serves the site with are installed as the site's certificate, so HTTPS carries on through the switch.
4. The code moves into the release layout: the live code is copied (not moved) into releases/000000-migrated, the .env goes to shared/.env, Laravel's storage to shared/storage, and current points at the release. This is the layout of every deployment in Vimonto Deploy.
5. Nginx switches in one reload: Vimonto Deploy writes its own site config, moves the platform's Nginx files for the site's names to /root/vimonto-takeover-backup/nginx, and checks the result with nginx -t. If Nginx does not accept it, the platform's files come back and the site keeps running as before. Otherwise Nginx reloads once. storage is copied again after the switch, so uploads that came in meanwhile are kept, and PHP-FPM reloads.
6. The old copy is removed: for a site that ran in place, everything in the site directory except releases, shared, current and .ssh is removed, because the release has it all. A site that already had releases (Forge's zero-downtime deployments, or Ploi's) keeps its folders, because its shared files live there.
7. Workers and features: the site's queue workers become the site's own workers, pointing into current. A worker that runs artisan horizon becomes the Horizon site feature, and a Laravel site whose schedule:run cron job was found gets the scheduler feature.
8. Push to deploy is switched off at the platform, so a push no longer deploys twice. The report says so; switch it on again here under the site's Deployments (Deploy on every push).
9. A Let's Encrypt certificate is requested for a site that came over with a certificate. Vimonto Deploy renews it from then on. If the request fails, the carried-over certificate keeps serving the site. If a Forge site had HTTPS but its certificate could not be read, the report says to request one under Domains and SSL.

6. Finish up#

Vimonto Deploy installs its monitoring agent and marks the server Active. The report ends with … is managed here now. Archive it in … so both stop managing it.

What stays the same?#

• The machine and its address. The server stays at your provider with the same IP address, so your domains and DNS need no changes. You keep paying the provider directly.
• The system user. The server keeps its system user, forge or ploi, and the sites stay in its home directory.
• Your sites keep running. The live code keeps serving until the Nginx switch, which is a single reload, so visitors notice nothing.
• Software, databases and data. Nothing is reinstalled or upgraded, and databases are not touched.
• Passwords. The server's sudo password and the database passwords are the platform's. Vimonto Deploy never had them, so it does not show them.

What do you do yourself afterwards?#

• Archive the server in Forge or Ploi, so only one of the two manages it. Archive it rather than delete it: deleting a server in the platform can delete the machine at your provider.
• Read the report below each server, and act on its warnings.
• Switch push to deploy on under the site's Deployments, and check the translated deploy script there.
• Deploy once with Deploy now to check that the site builds here.
• Ploi sites with extra domains: Ploi's API does not send them, so add them under the site's Domains and SSL.
• Remove the access recipe or script from Forge or Ploi if you like; it has done its work.
• Cancel your Forge or Ploi subscription once every server is over, if you no longer need it.

How do you undo a takeover?#

Nothing the platform made is deleted: it is in /root/vimonto-takeover-backup on the server.

To go back, log in as root, move the files back to /etc/supervisor/conf.d, /etc/nginx/sites-enabled and /etc/cron.d, restore a crontab with crontab -u forge /root/vimonto-takeover-backup/cron/forge.crontab, remove Vimonto Deploy's site config from /etc/nginx/sites-enabled, then run supervisorctl reread && supervisorctl update, nginx -t and systemctl reload nginx. The code of a site that ran in place now lives in releases/000000-migrated (through current), so point the platform's Nginx root at current or move the code back. Then delete the server in Vimonto Deploy.

What if an import fails?#

The server shows Failed with the error in its report, and the task's full output is on the activity page. Common causes:

• The access script did not run in time. The task says We could not log in to … as root on …. Check that the recipe or script ran in the platform, then try again in a few minutes.
• The server has no IP address in the platform, or is no longer in the account.
• A site directory is missing: only that site is skipped, the rest of the server is imported.

A failed server can be ticked again: fix the cause and click Import :count servers. A server that was never reached is removed again, so it is added fresh; one that was reached is reused. The import cannot be cancelled while it runs.

Frequently asked questions#

Do my sites go down during the import?#

No. The code is copied, not moved, and keeps serving until Nginx switches to the new config in a single reload. If Nginx does not accept the new config, the old one comes back.

Can I keep using Forge or Ploi alongside?#

Not for the same server. Both would write Supervisor programs, cron jobs and Nginx configs on it. Archive each server in the platform once it is imported. Servers you did not import stay in Forge or Ploi as they are.

Which servers can be imported?#

Any server in the Forge or Ploi account that has an IP address and that the platform can run a root script on. A server whose IP address is already in your organization shows Already here. Imported servers become app servers; their sites must have a valid domain and a directory that exists on the server.

What about Envoyer or zero-downtime sites?#

Sites that already deploy into releases (Forge's zero-downtime deployments, or Ploi's) are supported: the current release is copied into releases/000000-migrated and their folders are left in place. Envoyer is not read: a site deployed by Envoyer is imported from what Forge reports, so switch off its deployments in Envoyer and deploy from Vimonto Deploy.

Do I need to cancel my Forge or Ploi subscription?#

Not for the import: it needs an active account and token. Once every server is over and archived, you can cancel it yourself. Vimonto Deploy does not do that for you.

Is anything reinstalled or upgraded?#

No. The import does not run provisioning. PHP, the database, Nginx and the rest stay at the versions the platform installed.