servd

Creating a New Project, Step by Step

This article will guide you through the process of deploying a brand new project to Servd. We assume that you're familiar with how Craft works in general and that you're comfortable getting set up with a local development environment.

If you get stuck you can reach out to us via live chat and we'll be happy to lend a hand.

For an in depth overview of setting up a modern development workflow, including Servd, check out the CraftQuest video series here.

1. Get your project running locally #

The first step with any new Craft CMS project is to get it running locally. There's a lot of options for how to go about doing that, but we recommend using DDEV. It'll help you get a new project up and running in no-time and ensures your local dev environment is fully compatible with Craft from the outset.

Once you have a new project running locally you'll be able to start working on creating your content structure and twig templates as required. There's nothing Servd-specific you need to take into account at this point, so get to grips with Craft if you haven't already, and start creating something great!

2. Push your code to a remote git repo #

On Servd, we don't use FTP or rsync to move files around like in the olden-days. Instead we pull your code into our platform using git. This is a much safer, faster and more secure way to move your files around and allows us to pick out specific 'commits' or versions of your codebase when running deployments.

To allow us to pull your project using git, you first need to make sure it has been pushed up to a remote git host. You'll likely have come across these before, the most popular example of GitHub, but other alternatives include GitLab and BitBucket.

The process for getting your code pushed up to these can services can vary quiite a lot between them, so we won't cover specifics here, but you should be able to follow the Getting Started guides that they provide to ensure your code is stored safely within their platforms.

Servd has a direct integration with GitHub, GitLab and BitBucket, but we also support connections with any other git hosts that allow access via authenticated SSH. So feel free to chose whichever service works best for you.

3. Create a new project on Servd #

It's time to get set up within Servd!

Head to the Servd dashboard here: https://app.servd.host

If you don't already have an account, get yourself registered. If you are an existing user, get yourself over to the Create Project page so we can get started.

The Create Project flow within Servd will run through the majority of steps that you need to get your project up and running within the Servd platform. We'll walk through each step so that by the end of the process you'll have a fully functioning site hosted on Servd!

3.1 Project Name

You can choose any name that you'd like to be displayed inside the Servd dashboard and in any communications that we send to you about the project. You can change this later, so just set it to something that will remind you of what this Craft project is for.

3.2 Project Slug

Once your project is deployed on Servd we generate some temporary URLs which you can use to access the site before you've hooked up any of your final domain names. The Project Slug is used within these URLs and is also used in a few other places behind the scenes, such as naming databases.

You can set it to anything you like as long as it isn't already taken by another project on our platform. We recommend you set it to something related to your project.

You can't change this later, so make sure it's something you're happy with before proceeding.

3.3 Project Location

Servd has multiple different locations in which we are able to host your project. These are distributed geographically so you can choose where to host your project based on proximity to your users, or based on any data storage requirements.

This can't be changed later, so have a think about where would be best to place your project before continuing.

3.4 Connect to git

Now we're ready to pull in a copy of your project's files. We do this by connecting to the remote git host using the mechanism that you select here.

Choosing GitLab, GitHub or BitBucket will open an authentication dialog which allows you to grant Servd read access to your or your organisation's git repos. Connecting using these mechanisms also allows us to call the relevant service's APIs to get lists of commits and other data about your project's repo. This can be significantly quicker than the alternative connection type: Manual.

If you aren't using any of the three named services to host your repo, you can chose the Manual connection type. This allows you to pull a repo from any service which offer SSH based repo cloning. You'll need to copy the 'Deploy Key' which Servd provides and add it to the settings for your repo on the git host. Once added, Servd will test the connectivity to make sure we're able to pull your files.

3.5 Select a Branch and Commit

Now that we can connect to your repo you need to select a branch and a commit that you'd like to use for the first version of your project to be deployed to Servd.

Servd doesn't lock you into using a specific branch or commit moving forward, so there's no long-term consequences to what you select here, we're just choosing the files that we want to use for our very first deploy.

3.6 Craft Location

Servd needs to know the location of your Craft project files within the repo so that it can access them properly during deployments. The Craft Location is the path from the root of your repo to the files which are part of a normal, fresh Craft install. In other words, this should be the path withiin your repo where we can find Craft's composer.json file and config folder.

Servd will automatically try to detect where these files are located and ff it finds a match, it'll recommend that path as the location you should use. However, if it looks incorrect you can adjust the path as needed. Servd will also warn you if there's any required components missing from inside the repo so that you can make any necessary changes to your project files.

3.7 PHP Settings

Next up, we can chose the version of PHP and Composer that we'd like to use with this project. It's generally a good idea to match the settings that you've been using in your local development environment, but if you're unsure, PHP 8.0 and Composer 2 are the current best options.

3.8 Environment Variables

On Servd we use 'real' environment variables rather than .env files. This provides us with a little bit more flexibility around how they are applied in different contexts and it means we don't need to edit files in order to apply env var changes. Because of this we need to add them to the Servd dashboard. You can do this manually by copying and pasting each value into the appropriate boxes, or you can drag and drop an existing .env file as directed and Servd will parse the file for you, allowing you to make adjustments before saving.

Don't worry if you're not sure about some of the env vars at this stage, you can easily update them later if needed.

3.9 Building and Deploying

Now Servd has everything it needs to get your project built and deployed onto the platform. It will take a few minutes as we build any assets, install composer packages and get all of your project resources up and running.

At the end of the process your codebase will be deployed to the Servd platform, ready to receive requests.

4. Importing a database #

Now that your Craft Project's codebase is deployed, we need to make sure it has a database it can work with.

If you'd like to start with a completely fresh database with no pre-existing content, you can run through the Craft install process by visiting the /admin/install URL on your project's temporary URL.

However, normally you'll want to import a database dump taken from the project running in your local development environment.

4.1 Export your local database

There are three ways to get a full dump of your local database:

1. Use a CLI tool like mysqldump

2. Use a GUI tool like Navicat or TablePlus

3. Use the Database Backup tool in the Craft Control Panel (In the Utilities section)

Your sql file can be compressed using either zip or gz if desired.

4.2 Import into Servd

In the Servd dashboard, visit the Staging > Import page for your new project. You can use the database import tool here to load your database dump into your staging environment so that your deployed codebase has some content to show!

4.3 Check everything works

Visit the Overview page to grab the temporary URL and authentication details for your project. Open it up and see if everything is working!

If you see a Craft error, try visiting the Craft Control Panel. IF you then see a 'Craft is not installed yet' error message, double check that the DB_TABLE_PREFIX environment variable matches any table prefix that was included in your database dump. You can make changes to this environment variable on the Staging > Settings page in the Servd dashboard.

5. Add the Servd Plugin to your project #

Although it isn't necessary, adding the Servd Plugin to your project has several significant benefits:

• Warnings and hints for incompatibilities with the Servd platform
• Integration with the Servd Asset Platform
• Advanced caching functionality including static caching and {% dynamicInclude %} tags

On Servd we strongly encourage you to follow a uni-direction development workflow. Which means you should always make changes to your project's 'settings and configuration' in local development and allow Craft's Project Config functionality to apply those changes to your environments on Servd in an automated way.

Because of that, we'll need to get the Servd Plugin added to your project in your local dev environment. There's two ways to go about doing that:

1. Install the plugin using the Craft Plugin Store in the Craft Control Panel

2. (Preferred) Run composer require servd/craft-asset-storage from the command line and then 'install' the plugin from the Settings > Plugins page in the Craft Control Panel

In order to provide the plugin with access to the Servd Asset Platform we need to provide it with some credentials that it can use to authenticate. You can find these on the Project Settings > Assets page within the Servd dashboard.

To add these credentials to your project you can simply create two new environment variables:

• SERVD_PROJECT_SLUG
• SERVD_SECURITY_KEY

and set them to the values you took from the Servd dashboard.

Once added the plugin should stop showing any warnings about missing credentials. If you'd like to use the Servd Asset Platform for hosting your assets, you can now also change the 'type' of any existing Asset Volumes in Craft to be 'Servd Asset' volumes, instead of the default 'Local Filesystem' volumes. If you are configuring multiple asset volumes which all use the Servd Asset Platform, ensure each has a 'Subfolder' set to ensure the files don't all get mixed up.

If you have any Servd Asset volumes configured in your project and also have some existing assets that you need to upload, you can bulk upload those assets to the Asset Platform via a variety of mechanisms which you can read about here.

6. Explore static caching and other functionality #

We're pretty much there! Your site should now be up and running on Servd, with a database and assets all configured.

The last step is to explore some of the additional features that Servd offers, including Static Caching to make your site as fast as possible, or our CloudFlare integration which makes DNS management and DDoS protection a cinch.

Feel free to play with any of these settings in your Staging environment and test any changes to see what configuration works well for your project.

7. Add your Craft CMS license #

When you create a project, Servd will automatically setup a free Solo Craft CMS licence for you and associate it with the email of your user. If you need to upgrade to a Pro licence, then there are several options for registering it with your Servd project once you've purchased it.

8. Next steps #

If everything looks good and you'd like to activate your project's Production environment, all you need to do is select a subscription plan on the Plan page in the Servd dashboard. Once this has been confirmed your production environment will become available and you can get that set up manually, or run a Clone from the Production > Import page to copy your staging environment.

Finally, you'll likely want to add a domain name for your project! You can follow the instructions here to get that configured.