Let's Git Started 2: Your first project

Create a project

Anytime you want to deploy something on Upsun, you will begin by creating a new project. On Upsun, a project will be roughly equivalent to your repository. That is, a Upsun project will act as a remote for your site’s repository.

You will use the same codebase and project throughout these guides, making modifications along the way. Select where you would like to start based on the programming language of your choice, and run the provided command to clone the repository you will work from.

git clone https://github.com/platformsh-templates/php upsun-project

Open your editor and take a moment to take a look at the code. You will find a very simple “Hello world” application, that will include only a few files to start. You can run the application locally at localhost:8000 by running the following commands:

$ cd upsun-project
$ composer install
$ php -d variables_order=EGPCS -S localhost:8000 -t web

From the root of that project (cd upsun-project) run the following command, and answer the provided prompts:

upsun create

Note:

This command, and many steps after this point, rely on you having the Upsun CLI installed on your computer.

Read the documentation to install it now.

Note: project create

Project title: You need a unique name for each project, so title this one something memorable like My First Project.

Region: In general, choose the region that’s closest to where most of your site’s traffic is coming from. Here, go ahead and begin typing us-3.platform.sh and the CLI auto-completes the rest for you.

Plan: Select the development plan for your trial project.

Environments: Your default branch becomes the live production environment for your application. Additionally, other branches may be activated as fully running environments for developing new features. This value selects the maximum number of development environments the project allows. You can change this value later at any time.

For now, press Enter to select the default number of environments.

Storage: You can modify the amount of storage your application can use from the CLI and from the management console as well as upgrade that storage later once your project starts growing.

For now, press Enter to select the default amount of storage.

When the CLI has finished creating a project, it outputs your project ID. This is the primary identifier for making changes to your projects and you will need to use it to set Upsun as the remote for your repository in the next step. The command will also provide you with a link to the Upsun user interface - the Management console - which will have a URL that begins with console.upsun.com Open this link in your browser, as it will be relevant throughout the next steps.

upsun create may ask you whether you would like to automatically make the new project a remote. If you did not select yes at that point, you can configure it now with the following command:

upsun project:set-remote PROJECT_ID

You can also retrieve the project ID with the command upsun project:list, which lists all of your projects and their IDs in a table.

Configure an application

At this point you have created a Upsunp roject and configured it as a remote for your local repo. Before you push, you need to add some files that tell Upsun what to do with the application.

The first important file is .upsun.app.yaml, which configures how this repository should be built and deployed.

Create that file:

touch .upsun.app.yaml

Then copy and paste the following into that file:

name: app
type: 'php:8.0'
build:
  flavor: none
dependencies:
    php: 
        composer/composer: '^2'
hooks:
    build: composer install
web:
    locations:
        "/":
            root: "web"
            passthru: "/index.php"

This file defines an Application container, and specifically configures a few important things:

1. It gives the application a name.
2. It specifies its runtime type, as well as the version of that runtime that should be used.
3. It defines its build and relevant additional dependencies needed to build the application.
4. It contains a web block, which will either provide a start command or locations where traffic should be directed to when the server runs.

You may have seen similar configuration with other tools, and all of them represent an implementation of the DevOps principle of infrastructure-as-code. With infrastructure-as-code, services necessary for your application to run - like the version of a programming language and runtime environment - are committed alongside application code. From there they can be revised, and inherited by new branches.

The basic philosophy here is simple: just as your code depends on external code bases (dependencies), it also depends on specific infrastructure. Infrastructure is a dependency of your applications, so it should be committed.

Handle requests

The second file you’ll need is a .upsun/routes.yaml file. This file defines a separate Router container, and controls how requests are handled when they come to the site.

Add that file:

mkdir .upsun && touch .upsun/routes.yaml

Copy and paste the following into that file:

"https://{default}/":
    type: upstream
    upstream: "app:http"

"https://www.{default}/":
    type: redirect
    to: "https://{default}/"

This file has defined two things:

1. All traffic should be directed to an upstream application, in this case the same application defined in the previous step named app.
2. Any requests made to the www subdomain should redirect to that same original domain.

You may also notice a placeholder value, {default}. This placeholder is special - it allows the same configuration defined above to work across development environments. More on that later.

Deploy

With these two files added, you’re now ready to deploy the application to Upsun. Commit and push the changes

$ git add .
$ git commit -m "Add Upsun configuration."
$ git push upsun main

You will see in your terminal your first glimpse at the Upsun build-and-deploy process. In the rest of the guide, each step of this process, as well as how they work, will be covered in much more detail. You can also visit the management console you opened before, and view the running process on Main - your project’s current production environment.

When the process completes, you should see the same site you had run locally now running at a random generated URL on Upsun. You can find the link for this environment in the management console, or retrieve it by running the command upsun url.