Create a site on your server

A site in SrvYard is one application on one of your servers: a Laravel app, a WordPress blog, a Next.js front end or a folder of static files. Creating the site is the step that prepares the server for it. SrvYard creates the Linux user (or reuses the server's main one), the PHP-FPM pool for PHP sites, the Nginx configuration, a placeholder page and, when you give it a repository, the first deployment.

This article walks through the whole form with a Laravel application. The other site types use the same form with a few fields added or removed, and every difference is called out below. By the end you will have a site in the Ready state, answering on its own domain.

Before you begin#

• A ready server that runs Nginx. The server must be connected and finished installing. A server that is still installing, or that SrvYard cannot reach, is listed in the form but cannot be chosen: its state is shown in brackets next to its name. If you have no server yet, start with Servers.
• Room in your plan. The Hobby plan includes 3 sites; Pro and Business have no site limit. When you are at the limit the form shows a Site limit reached warning, tells you how many sites your plan includes and how many you use, and the Create site button stays disabled.
• A repository, if you want one. Either connect GitHub, GitLab or Bitbucket under Source control in the sidebar first, or have the clone address of a public repository ready. A repository is optional, but read the note under Choose where the code comes from before you skip it.
• A domain you control, if you do not want the free one. You will need to point its DNS records at the server yourself.
• The right to create sites. Members whose role cannot manage sites do not see the New site button.

1. Choose the site type#

Open Sites in the sidebar and press New site. A menu groups the types by what they run.

1. Press New site at the top right of the Sites page.
2. Choose a type. Here we pick Laravel.

The menu offers:

The type is more than a label. It decides the default web directory, which fields the form asks for (WordPress asks for an administrator, Next.js for a Node version and port), and the deploy script the site starts with. You can change the script later, but you cannot change the type.

2. Choose where the code comes from#

The form has two columns. On the left are the server and the source of the code; on the right are the domain and the options.

1. Server. Pick the machine the site will live on. Each entry shows the server's name and IP address, and a state in brackets when it cannot take sites yet. The PHP versions, database engines and Nginx templates offered further down come from this server, so choose it first: the form changes when you change it.
2. Source control. Three tabs: No repository, Git provider and Custom Git URL.
3. Free domain (or Domain). Covered in step 4.
4. Advanced settings. Covered in step 5.
5. Create site. Covered in step 6.

The three source choices behave like this:

• No repository. The site starts with a placeholder page and SrvYard keeps the standard deploy script ready. The form warns that a site created without a repository cannot get one later, so treat this choice as final unless you are building a site you will manage by uploading files.
• Git provider. Use a connection you made under Source control. Choose the connection, optionally narrow it to one account or organisation (Workspace on Bitbucket), pick the repository from the list, then pick the branch. If you cannot find the repository, use Type it manually to enter owner/repository yourself.
• Custom Git URL. Use this for a public repository or any host that SrvYard has no provider for. An https:// address works for public repositories. An SSH address such as [email protected]:owner/repository.git makes SrvYard create a deploy key that you add to the repository.

When a repository is set, the options on the right come alive:

1. Custom Git URL is the tab chosen in this example.
2. Git URL. The address SrvYard will clone.
3. Branch. Defaults to main. The branch is what push to deploy listens to, and you can change it later in the site settings.
4. Install Composer dependencies. On by default for Laravel, Symfony and Statamic. SrvYard adds composer install to the deploy script. Turn it off if the repository has no composer.lock.
5. Push to deploy (with Generate a site deploy key just above it). Push to deploy makes every push to the branch start a deployment. The deploy key option makes the site clone with its own read-only key instead of your account's access token.

Connect to a database#

Under the repository fields there is a Connect to database switch. It creates a database and a user on the server and puts the connection details into the site's environment. It needs a database engine on the server. If the server has none, the form says so and sends you to the server's Services tab to install one first. WordPress and phpMyAdmin require a database, so for those types the switch is part of the form rather than an option.

3. Check what the server offers#

Before you move on, make sure the server you chose is the one you meant. The advanced summary line under Advanced settings changes with the server: it shows the PHP version the server uses by default, and a server without any PHP version shows PHP none. If it does, install a PHP version on the server's PHP tab first.

4. Choose the domain#

Every site needs a name. SrvYard offers two ways to get one.

A free domain. The form starts on Free domain. Each site includes a free name under srvy.sh, such as acme-launch.srvy.sh, that SrvYard points at your server for you. It suggests a random one; type your own in Subdomain or press Generate another. SrvYard checks the name while you type and tells you whether it is available. A free domain is the quickest way to a working site, but Let's Encrypt allows only a limited number of certificates per week for the shared srvy.sh zone. If issuing a certificate fails for that reason, use your own domain.

Your own domain. Press Use custom domain, type the domain (for example app.acme-studio.example) and press Change under it to open the Configure dialog.

1. Wildcards. Off answers only on the domain you typed. On answers on every subdomain, such as blog.app.acme-studio.example. A wildcard certificate needs DNS validation, which you set up later on the site's SSL tab.
2. Redirects. Redirect from www. sends www.example.com to example.com and is the recommended choice. Redirect to www. does the opposite. No redirect answers only on the exact name you typed.
3. Save closes the dialog. The summary under the domain field is updated to match.

For a custom domain, remember that SrvYard does not own your DNS: create an A record (and AAAA if the server has an IPv6 address) at your DNS provider that points the domain at the server's IP address. Until it does, the domain will not reach the site and an HTTP certificate cannot be issued.

5. Review the advanced settings#

Press Advanced settings to see the choices that are fixed once the site exists.

1. Root directory. The folder of the repository that holds the application. Composer and npm run here. It defaults to /; change it for a monorepo where the app lives in a subfolder. It cannot be changed after the site is created.
2. Web directory. The folder Nginx serves, relative to the root directory. Empty means /public.
3. PHP version. The server's default is preselected. Only versions installed on the server are listed.
4. Use website isolation. Gives the site its own Linux user and its own PHP-FPM pool, so one site cannot read another's files. It is off by default, in which case the site runs as the server's main user like every other site on it. This cannot be changed later.

Below those fields the dialog also has the Frontend package manager (npm by default) and the Build command (npm run build), a Zero downtime deployments switch (offered for the site types that support it), and sections for Composer authentication and npm authentication where you can store credentials for private package registries. They are saved encrypted and written to auth.json or .npmrc for the site.

6. Create the site and watch it install#

Press Create site. SrvYard saves the site and takes you to its page with a short "Creating the site..." message. Behind the scenes it works through the installation on the server: it creates the user and folders, writes the PHP-FPM and Nginx configuration, adds the domain and, when you chose a repository, starts the first deployment. A site with a free domain also asks for its Let's Encrypt certificate by itself as soon as the name resolves to your server.

While this runs the site badge shows Creating and then Installing, with a progress bar and the current step. Two things can end it:

• Ready. Everything worked. With a repository, a first deployment is started automatically; open the Deployments tab to follow it.
• Installation failed. The page shows the error. Fix the cause (a full disk, an unreachable server, a name that is already taken), then press Retry installation on the site. Steps that already finished are skipped. View log on the same card shows what the server printed.

On a finished site:

1. The Ready badge says the site is installed and serving.
2. The tabs run along the top: Deployments, Environment, SSL, Domains, Logs, Commands, Processes, Network, Settings, Observe and Backups. Every article in this section is about one of them.
3. The Domains card lists every hostname the site answers on, with Points here when its DNS record reaches your server.
4. Settings holds the repository, branch, PHP version, Nginx configuration and, at the bottom, Delete site.

7. Find your sites later#

The Sites page lists every site in the organisation with its tags, server, PHP version, repository and status.

1. Search matches the site name and the repository.
2. Status filters by Ready, Installing, Failed and the other states.
3. Server shows the sites of one machine.
4. Press a site name to open it.

The View menu at the right of the filters chooses which columns are shown.

Troubleshooting#

• The server I want is greyed out. Its state is written next to its name. A server that is installing, disconnected or deleted cannot take sites. Wait for it to become ready or fix the connection from the server page.
• "Sites can only be created on a ready server that runs Nginx." Database and cache servers do not run Nginx. Create the site on a web or app server.
• The free subdomain is not available. Someone has taken it. Press Generate another or type a different label.
• The Create site button is disabled. Check for a Site limit reached warning, for a server that is not selected, and for a subdomain that is still being checked.
• The site stays on "Installing" for a long time. The progress card on the site page names the current step. A slow server can take several minutes; if the step never changes, check that the server is still connected.
• The domain shows the placeholder page, or does not load. The DNS record does not point at the server yet. Open the Domains tab and look for Points here next to the name.
• The site installed but the first deployment failed. That is a problem in the deploy script or the code, not in the installation. Read the log on the Deployments tab; Write and test a deploy script explains each step.
• I skipped the repository and now want one. The form warns that this cannot be done later. Create a new site with a repository and move the domain across.

Related#

• Write and test a deploy script: what runs on every deployment and how to change it.
• Get a free Let's Encrypt certificate: serve the site over HTTPS.
• Servers: connect or provision the machine your site runs on.