How a deploy works

When we deployed company-site in the tour, four commands did the work: deploy, commit, apply, and verify. This page shows what each one does, using the same WordPress site.

Prepare, save, then switch on

Nextweb keeps deciding what we want separate from making it happen. deploy and commit describe a site and save that description, and nothing starts until apply. That way we can prepare a change, look it over, and switch it on when we're ready. Afterwards, verify tells us whether the result matches what we asked for.

Along the way a site has one of three statuses. It is pending from the moment we deploy it until apply finishes, and applied after that. If its apply fails, it is failed: verify names what went wrong, and the next apply tries it again.

deploy prepares the site

deploy company-site to www.example.com using wordpress names the site, gives it a domain, and chooses what it's built from. Here wordpress is the template, and the WordPress package has to be installed first.

Nextweb then:

• creates the site's folder, nextweb_server/sites/company-site/, and copies WordPress into sites/company-site/wordpress/, so every site has a copy of its own;
• writes sites/company-site/.nextweb/state.json, which records the domain, the database name and user Nextweb will create, and the status pending;
• adds the site to the working configuration, the draft of changes that haven't been saved yet.

No database, runtime, or web server changes happen yet.

configure stages settings

configure enters configuration mode, and the prompt changes to nextweb(config):/>. In this mode, set changes values in the working configuration, for example set company-site admin-email admin@example.com, and exit returns to the normal prompt. Changes made here wait in the working configuration until we commit.

The tour skips this step, because WordPress asks for its own site title and email during its setup.

commit saves the configuration

commit "Deploy company website" checks the working configuration and writes it to nextweb_server/config/nextweb-services.json, along with our note. The site is now part of the saved configuration, still marked pending.

apply switches it on

apply turns the saved configuration into running software. Because that can stop or restart services, it asks for confirmation first, and apply -y answers yes up front.

For our WordPress site, apply:

1. installs the WordPress package if it's missing;
2. starts MariaDB as the mariadb service, which every WordPress site shares;
3. gives the site its own listening port, between 4001 and 4099;
4. creates the site's database and database user;
5. starts the site's PHP: two PHP processes, so a slow request does not hold up the others;
6. writes WordPress's wp-config.php with the database details;
7. registers the site with the web server, and as a service of its own that service company-site status can report on;
8. reloads the web server so it listens on the site's port, prints the Visit address, and marks the site applied. A reload leaves the other sites serving.

MariaDB and the site keep running as services after apply. When Nextweb starts, it starts mariadb before the sites. If either one stops unexpectedly, Nextweb starts it again, and stopping Nextweb stops them both. service mariadb status reports on the database.

A later apply does only what is due. It provisions new sites, sites whose settings changed, sites whose last apply failed, sites whose service is not running, and Node.js sites whose package was upgraded. A site that is unchanged and running is left alone, with a line such as company-site: unchanged, running. One site that fails does not stop the others: it is marked failed, and the rest are still applied.

verify checks the result

verify company-site looks at the site from the inside and the outside. It confirms that wp-config.php exists, that the state file says applied, that the database settings are in place, and that the web server has an entry for the site. Then it asks the site for a page and expects status 200 and a WordPress page in return. It ends with the Visit address and either All checks passed or the first thing that needs attention.

undeploy removes a site

undeploy takes a site out of service. It stops the site's service, removes its web server entry and its port, and takes it out of the configuration, after asking first (-y answers yes):

nextweb:/> undeploy company-site

The site's folder, nextweb_server/sites/company-site/, stays, and so does a WordPress site's database, so deploying the same name again picks up where it was. undeploy company-site --purge deletes the folder and drops the database and its user too. If the database cannot be dropped, the folder is kept and the same command can be run again to finish.

Where everything lives

nextweb-tour/
  nextweb                          the program
  nextweb_server/
    config/nextweb-services.json   the saved configuration
    runtime/                       PHP and MariaDB, installed once
    sites/company-site/
      wordpress/                   the site's own copy of WordPress
      .nextweb/state.json          what Nextweb knows about the site

Packages are installed once for the whole Nextweb folder. Each site gets its own folder under sites/, with a record of how Nextweb set it up. A WordPress site keeps its own copy of WordPress there, and WordPress keeps that copy up to date itself as new releases come out. A Node.js application runs from its installed package instead, and keeps its own files in sites/<site>/data, as Your application on Nextweb describes.