Getting Started
Getting Started¶
Requirements¶
Before getting started, check that you have Git installed and SSH properly configured as SymfonyCloud relies on both quite heavily. This also means that your project must use Git as its version control system.
Installing the CLI Tool¶
To manage your Symfony projects with SymfonyCloud, install the symfony
CLI tool:
1 | $ curl -sS https://get.symfony.com/cli/installer | bash
|
Note
On Windows, download and run the Windows installer instead.
Then, authenticate with your SymfonyConnect credentials:
1 | $ symfony login
|
You are now all set! To get started with the Symfony CLI tool, run symfony
to get some common commands or symfony help
to list all available commands.
If you want more detailed information about a command, use symfony help
COMMAND_NAME
, or symfony COMMAND_NAME --help
. The second one is useful
when you have already added some arguments and/or flags like in symfony
something --flag arg --help
.
Deploying a Project on SymfonyCloud¶
There are three steps needed to deploy a project on SymfonyCloud:
- Configure the project by describing its infrastructure (including its services);
- Create the project on SymfonyCloud;
- Deploy the project.
If you want to deploy a sample project on SymfonyCloud, create a Symfony Demo project with the following command:
1 2 | $ symfony new --demo /path/to/demo
$ cd /path/to/demo
|
Configuring the Project¶
SymfonyCloud manages the entire infrastructure of your project, from code to services (databases, queues, search, …), from email sending to crons and workers. This infrastructure is described through configuration files, stored along side your code.
From within the project’s directory, generate a sensible default SymfonyCloud configuration:
1 | $ symfony project:init
|
The command detects the language and the framework used by the project and it
generates a default configuration in the following files:
.symfony.cloud.yaml
, .symfony/services.yaml
, .symfony/routes.yaml
,
and php.ini
.
Don’t forget to commit the new files in your repository:
1 2 | $ git add .symfony.cloud.yaml .symfony/services.yaml .symfony/routes.yaml php.ini
$ git commit -m "Add SymfonyCloud configuration"
|
If you have a closer look at .symfony.cloud.yaml
for a Symfony project, you
will notice the calls to symfony-build
and symfony-deploy
scripts during
the build and deploy hooks respectively. These scripts register some environment
variables depending on the services you require (names match the one expected by
Symfony recipes). They also build the application cache and run the database
migrations if any. They should cover most use cases for Symfony applications.
Note
By default, the symfony new
command does not automatically configure
the project for SymfonyCloud; the --cloud
flags allows you to create a
project and automatically configure it for SymfonyCloud at once.
Creating the Project in the Cloud¶
Then, create a new SymfonyCloud project:
1 | $ symfony project:create --title=demo --plan=development
|
Caution
Each SymfonyCloud project is billed monthly according to the chosen plan,
except the first seven days of your currently active trial development project.
When you benefit from a free trial, don’t forget to accept billing using
symfony project:billing:accept
if you want to keep this project after the
end of the free trial, without this confirmation the project will get suspended
then deleted. When you don’t use of project anymore, don’t forget to
delete it or you will continue to be billed for it.
Deploying the Project¶
Tip
If you didn’t do it yet, now is the perfect moment to upload your SSH key
to SymfonyCloud. You can do it using the symfony account:ssh:key:add
,
use symfony account:ssh:keys
to see the list of keys you already
uploaded.
Finally, deploy the project to the cloud:
1 | $ symfony deploy
|
Note
If you have private dependencies, you might need to authorize SymfonyCloud
to get them. Use symfony project:deploy-key
displays the SSH key
SymfonyCloud uses.
If you have created a Symfony demo application, you need to set some environment variables to make it work properly:
1 | $ symfony var:set --file=.env
|
Check that everything went fine by opening the deployed URL:
1 | $ symfony open:remote
|
Note
Note that SSL has been configured automatically for your application thanks to Let’s Encrypt.
Working on a Project¶
Now that the project is deployed, let’s describe a typical scenario where you want to fix a bug or add a new feature.
First, you need to know that the master
branch always represents the
production environment. Any other branch is for developing new features,
fixing bugs, or updating the infrastructure.
Note
At the moment, the production branch can only be named master
. Please
read about how to make it work for you if you want to
use another name on your project.
Let’s create a new environment (a Git branch) to make some changes, without impacting production:
1 2 | $ git checkout master
$ symfony env:create feat-a
|
This command creates a new local feat-a
branch based on the master
branch and activate a related environment on SymfonyCloud. If you have some
services enabled, the new environment inherits the data of the parent
environment (the production one here).
Let’s make some simple visual changes. If you have created a Symfony demo
application, edit the templates/default/homepage.html.twig
template and make
the following change:
1 2 3 4 5 6 7 8 | # templates/default/homepage.html.twig
{% block body %}
<div class="page-header">
- <h1>{{ 'title.homepage'|trans|raw }}</h1>
+ <h1>Welcome to the SymfonyCloud Demo</h1>
</div>
<div class="row">
|
Tip
If you want to check that the change is correct on your local machine, run
symfony server:start
and symfony open:local
to test it in your
local browser.
Commit the change:
1 2 | $ git commit -a -m "Update text"
$ # in a real-life scenario, you would push the change to the upstream Git repository
|
And deploy the change to the feat-a
environment:
1 2 3 4 5 | # the 'env:create' command checkouts into the new branch automatically,
# but if you changed it for some reason, checkout the 'feat-a' branch again
# $ git checkout feat-a
$ symfony deploy
|
Browse the new version and notice that the domain name is different now (each environment has its own domain name):
1 | $ symfony open:remote
|
Iterate by changing the code, committing, and deploying. When satisfied with the changes, merge it to master, deploy, and remove the feature branch:
1 2 3 4 5 | $ git checkout master
$ git merge feat-a
$ git branch -d feat-a
$ symfony env:delete feat-a
$ symfony deploy
|
Note
Note that deploying production was fast as it reused the image built on the
feat-a
environment.
Tip
For a long running branch, you can keep the code up-to-date with master
via git merge master
or git rebase master
. And you can also keep the
data in sync with the production environment via symfony env:sync
.
Deleting a project¶
Use symfony project:delete
to delete a SymfonyCloud project (optionally
specifying the project ID using the --project
flag); use
symfony projects
to list all active projects under your account.
This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.