Getting Started with Sulu CMS on Vagrant The Right Way™

In this tutorial, we’ll learn how to get started with Sulu CMS the right way – meaning, we’ll deploy a Sulu “Hello World” instance using Homestead Improved and be mindful of performance issues and configuration values while we’re at it. We’ll also cover some common pitfalls, all in an attempt to get a good base set up for future Sulu tutorials. It is recommended you follow along with the instructions in this post and drop a comment with any problems you might run into.

Many thanks to Daniel Rotter and Patrik Karisch for helping me iron this process out!

Note that it’s highly recommended to be familiar with Homestead Improved before starting out. If you’re not at that level yet, you should buy our amazing book about PHP Environment Basics.

---

[Sidenote] Enter your project’s name

This tutorial is dynamic in that it will replace all placeholders in the text below with the project name you define in the field under this paragraph. That way, the commands become very copy/paste friendly.

Project name:

Generated slug: my_sulu_project

---

OS X Vagrant Folder Sharing Problems

When using the NFS folder-sharing mode on OS X hosts, the vagrant-bindfs plugin will be necessary. Install it alongside your Vagrant installation with vagrant install plugin vagrant-bindfs. This is a one-time thing that’ll prevent many, many headaches down the line if OS X is your main OS.

The rest is all automatic and already configured in the Homestead Improved instance, you don’t need to do anything else.

Vagrant Up

The first thing we do is, of course, clone the HI repo.

git clone https://github.com/swader/homestead_improved my_sulu_project
cd my_sulu_project

Next, let’s configure the shared folders:

bin/folderfix.sh

This made the current working directory shared with the /Code directory inside the VM. That way, the changes made in this folder will be reflected inside the virtual machine and vice versa.

Like with any Symfony app, Sulu requires a custom virtualhost configuration for Nginx. We’ve made things easier by turning it into a “project type” in Homestead Improved, so all you need to do is the following modification on Homestead.yaml:

• add the nfs folder sharing type (on OS X and Windows 10)
• add the sulu project type and change its document root subfolder to web

The relevant sections should end up looking like this:

...

folders:
    - map: /Users/swader/vagrant_boxes/homestead/my_sulu_project
      to: /home/vagrant/Code
      type: nfs

sites:
    - map: my_sulu_project.app
      to: /home/vagrant/Code/my_sulu_project/web
      type: sulu

Finally, let’s fire up the VM.

vagrant up; vagrant ssh

Protip: Useful aliases to set up for future use:

alias vh='vagrant halt; cd ..'
alias vush='vagrant up; vagrant ssh'

Setting up Sulu

Creating the Project

Let’s install Sulu’s standard edition (the minimal edition is actually “standard” now, whereas the old “standard” is deprecated – they’re working on renaming this).

cd Code
composer create-project sulu/sulu-minimal my_sulu_project

Note that the docs currently suggest adding a -n flag at the end of that Composer command which means “No interactive questions”. I like it when an installer asks me about things I’m supposed to configure anyway, so I omitted it.

The installation will take a while because Symfony has a lot of dependencies (see the Polyfills sub-section in the Pitfalls and FAQ section below).

Once the packages have been downloaded, the installer will ask some questions about the database, email, and other user-fillable data. The only values you should have to set there will be the database related ones, and maybe the secret token or mailer settings if you know them by heart:

Some parameters are missing. Please provide them.
database_driver (pdo_mysql):
database_host (127.0.0.1):
database_port (null):
database_name (sulu): homestead
database_user (root): homestead
database_password (null): secret
database_version (5.5):
mailer_transport (smtp):
mailer_host (127.0.0.1):
mailer_user (null):
mailer_password (null):

...

You can always modify these manually after the fact by editing the app/config/parameters.yml file.

Webspaces

It’s time to set up a webspace. A webspace is like a single website inside of your Sulu installation. For example, think of SitePoint’s free, public facing side as one webspace, and the Premium side as another.

There’s an app/Resources/webspaces/example.com.xml file which should be renamed to match your project: app/Resources/webspaces/my_sulu_project.xml.

In that file, two values (name and key) need to be updated to match the project:

<?xml version="1.0" encoding="utf-8"?>
<webspace xmlns="http://schemas.sulu.io/webspace/webspace"
          xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://schemas.sulu.io/webspace/webspace http://schemas.sulu.io/webspace/webspace-1.1.xsd">

    <name>{{My Project}}</name>
    <key>my_sulu_project</key>

    <!-- ... -->
</webspace>

The filename and the key value do not have to match, but it’s usually clearer if they do.

Something from the docs to keep in mind:

Changing the <key> of a webspace later on causes complications. We recommend to decide what key to use before you build the database in the next step.

Create the Database

If you haven’t already, you should create the database. Homestead Improved comes with a default homestead database, accessible by the user homestead with the password secret, so if you’re using it, you probably don’t have to do anything.

Build

As a final preparatory step, we need to run the (arguably difficult to remember) command:

php bin/adminconsole sulu:build dev

This will prompt us to confirm the following:

Options:

  - nodeps: false
  - destroy: false
  - help: false
  - quiet: false
  - verbose: false
  - version: false
  - ansi: false
  - no-ansi: false
  - no-interaction: false
  - shell: false
  - process-isolation: false
  - env: 'dev'
  - no-debug: false

Before confirming, let’s quickly explain each of these flags that could be passed into the build command. These are, in fact, the flags of the Symfony Console component – the reason why they’re echoed our here like this is unclear.

A note about terminology: a build target is a “recipe” for an application. A set of instructions to be executed to get the app to its target. In the case of dev (which is a build target here, not an environment), this includes building assets, publishing routes, creating users, and much more. Another target, prod, does the exact same thing, but without generating default users (a security risk, hence prod for production). To see which targets are available, just run the plain bin/adminconsole sulu:build.

1. nodeps: when building, dependencies of the targets will also be built by default. If you wish to prevent this, the --nodeps flag is used. A dependency could be another target, a specific fixture in a database, and so on.
2. destroy: destroys existing data in an application. Useful for a full restart, a factory reset of sorts.
3. help: if added to the command like so: bin/adminconsole sulu:build dev --help, explains what the build command does.
4. quiet: produces no output from the build process whatsoever. If this flag is present, the next flag, verbose, has no effect.
5. verbose: how much information the process outputs. Can have a value from 1 to 3, like so: --verbose=3.
6. version: displays the application’s version. If used, nullifies the sulu:build dev part of the command.
7. ansi: if set to true, decorates (colors and formats) the output messages with ANSI.
8. no-ansi: disables ANSI decoration, helpful in cases like these
9. no-interaction: will attempt to auto-confirm all choices at their default/assumed value instead of asking for input from the user.
10. shell: launches shell mode, which makes the console interactive, as in, lets you use it as you would, for example, use MySQL when logged into it. You can then execute all the Console commands without prefixing them with bin/adminconsole. Nullifies all other commands if used, shell takes precedence and sulu:build dev would have to be re-issued from inside the shell.
11. process-isolation: launches the commands about to be executed as separate processes
12. env: the current environment’s name (dev by default). Changed with --env=prod.
13. no-debug: disables debug mode. In other words, it disables the collection of dev debug data like performance bottlenecks, logs, etc., which is useful if you want the performance of prod but don’t want to switch the environment from dev.

Confirm the command.

Log In

To inspect the front end of the application, visit my_sulu_project.app/ in the browser. To log in as administrator, visit my_sulu_project.app/admin/ and log in with admin/admin.

Not much to look at but hey, it works!

The back end is much prettier. Feel free to play around in this UI – in the next post, we’ll get started with developing things in Sulu!

Pitfalls and FAQ

There are several questions that might be rolling around in your head after this, as they were in mine, so let’s get to them. As you post others, we’ll make sure we update this list with answers from the Sulu team themselves.

Is Sulu good for a news website?

Not by default, which is admittedly odd given the fact that it’s an “enterprise CMS”. The default content setup is a tree structure, where each page can have sub-pages and so on. This doesn’t work well for a flat list of files. What does, though, is the SuluArticleBundle – an under-development bundle that lends itself perfectly to regular posting of articles.

Keep this in mind when launching a high-publish-frequency site on Sulu.

Polyfills?

You may have noticed that different polyfills of various past PHP versions get installed during the installation process. This slows the process down, and bloats the project. This is because they’re a dependency of Symfony/symfony, which is a dependency of Sulu. Symfony includes these because the minimum PHP requirement is version 5.5.9 (for now), and these polyfills need to be in place to support functionality that only newer versions of PHP have.

There’s a discussion under way about hacking these away during installation.

Will Sulu follow Symfony into Symfony 4 and Flex?

Yes, the Sulu team is looking at the Flex project and following Symfony 4’s progress. It’s not clear what effect Flex and Symfony’s new setup will have on Sulu in time, and how long it’ll take to get them in sync – it all depends on the types and magnitude of changes the new version brings, but even right now you can test Sulu 1.6.0. RC1 which uses the newest Symfony 3.3. All you need to do is modify the create-project command slightly:

composer create-project sulu/sulu-minimal=1.6.0-RC1 my_sulu_project

Conclusion

Sulu has matured as a platform, and is becoming more and more DX-friendly by the day. My hope is that with tutorials like these I’ll bring the concepts closer to you and help you understand the power this Symfony-based CMS holds, and that it makes sense as a starting point for many of your projects, regardless of size.

If anything about this post hasn’t been properly explained, or you’ve run into any difficulties with setting things up, please don’t hesitate to leave a comment below and tell us about the issues.