Up(sun) and Running with Twill

Overview

This guide provides instructions for deploying and working with Twill, an “open-source CMS toolkit for Laravel” on Upsun, by Platform.sh. If you’re not familiar with Forem, it’s a Laravel package that helps developers rapidly create a custom CMS that is beautiful, powerful, and flexible.

Before we dive in, let’s establish some assumptions that we’ve made about you to ensure you can follow this guide successfully:

• You have an account set up on Upsun.com and the necessary permissions to create a new project
• You have the Upsun CLI installed
• You have authenticated in the CLI
• You have the same PHP version installed locally that you want to use in your application container, and it has both pdo and pdo_mysql extensions enabled.

Setting up the application and repository

First, we need to start a Laravel project. From a terminal/command prompt, create a new Laravel project locally:

composer create-project laravel/laravel laravel-twill && cd laravel-twill

Composer will create a new Laravel project for us, and then we’ll cd into the new directory. Once the project is created and we’re in the new directory, we’ll go go ahead and initialize our git repository.

From your terminal/command prompt:

git init .

By default, git will name the initial branch master. I’m going to rename mine to main and will reference this name throughout the remainder of this guide. To rename the branch, from your terminal/command prompt:

git branch -m main

Next we need to add Twill as a dependency to our Laravel project. In your terminal/command prompt:

composer require area17/twill:"^3.4"

Composer will add Twill along with all of Twill’s dependencies to your project. With Twill now added, we’re ready to set up some base Upsun configuration files. In your terminal, start the project initialization:

upsun project:init

The CLI should automatically detect that your stack is based on Laravel. It will then select PHP as your runtime, and Composer as your dependency manager. Next, it will prompt us for the project’s name (you can select the default) and lastly, the services we need. In this case, select MariaDB and Redis.

upsun project:init
Welcome to Upsun!
Let's get started with a few questions.

We need to know a bit more about your project. This will only take a minute!

What language is your project using? We support the following: [Ruby]

✓ Detected stack: Laravel
✓ Detected runtime: PHP
✓ Detected dependency managers: Composer
Tell us your project's application name: [laravel-twill]


                       (\_/)
We're almost done...  =(^.^)=

Last but not least, unless you're creating a static website, your project uses services. Let's define them:
Select all the services you are using:
Use arrows to move, space to select, type to filter
> [x]  MariaDB
  [ ]  MySQL
  [ ]  PostgreSQL 
  [x]  Redis
  [ ]  Redis Persistent
  [ ]  Memcached
  [ ]  OpenSearch

After selecting your services and hitting enter, the Upsun CLI will generate two new files for you:

• .environment in the root of the Forem repository and a new directory
• .upsun with a single file inside named config.yaml

Now go ahead and follow the CLI’s instructions to git add and git commit.

Leverage environment variables

While the project:init command correctly identified our project as being Laravel-based, and correctly set up our Upsun configuration files for success, there are a few changes we’ll need to make in order to deploy Twill. Upsun does not read environment variable values from .env but does provide a way to generate environment variables via script. The .environment file that the CLI generated previously runs as a script in dash when the container starts and on all SSH logins. It can be used to set any environment variables directly, such as the PATH variable. Perfect!

To start, we need to add the APP_KEY and value that Laravel generated for us in the .env file into our .environment. With your favorite IDE, open up the .env file and copy the line that starts with APP_KEY. Next, open the .environment file. Scroll down to the bottom, just past export REDIS_URL. On a new line, type export and paste in the line we just copied. It should look similar to the following:

export APP_KEY=base64:TGFyYXZlbCArIFR3aW/sICsgVXBzdW4gPT0gQXdlc29tZQo=

Next up, we need to modify the database-related environment variables so we can use a tunnel to our database container more easily. Open the .environment file again and at the top of the file, add the following:

export RELATIONSHIPS_JSON="$(echo $PLATFORM_RELATIONSHIPS | base64 --decode)"

Now, locate the variables starting with DB_. They should be located right between the comments: # Set database environment variables and # Set Laravel-specific environment variables. Once you’ve found those variables, replace them with the following:

export DB_HOST="$(echo $RELATIONSHIPS_JSON | jq -r '.mariadb[0].host')"
export DB_PORT="$(echo $RELATIONSHIPS_JSON | jq -r '.mariadb[0].port')"
export DB_PATH="$(echo $RELATIONSHIPS_JSON | jq -r '.mariadb[0].path')"
export DB_DATABASE="$DB_PATH"
export DB_USERNAME="$(echo $RELATIONSHIPS_JSON | jq -r '.mariadb[0].username')"
export DB_PASSWORD="$(echo $RELATIONSHIPS_JSON | jq -r '.mariadb[0].password')"
export DB_SCHEME="$(echo $RELATIONSHIPS_JSON | jq -r '.mariadb[0].scheme')"

Save the file, and commit everything to your repository.

git add . && git commit -m "initial commit"

Create the Upsun project

Before we can deploy our application, we’ll need to create a new project on Upsun. To do so, we’ll type the command below into command line:

upsun project:create

The CLI tool will now walk you through the creation of a project by asking you for:

• Your organization
• The project’s title
• The region you want the application housed
• The branch name (use the same one you set earlier) For now, allow the CLI tool to set Upsun as your repository’s remote, and then select Y for the tool to create the project. The Upsun bot will begin the generation of your Upsun project and once done, will report back the details of your project including the project’s ID, and URL where you can manage the project from the Upsun web console. Don’t worry if you forget any of this information, you can retrieve it later with:

upsun project:info

You can also launch the web console for your project at any time by doing the following:

upsun web

First push

We’re finally to the point where we can push our repository to Upsun and have it perform the first build:

upsun push -y

This first push will take a few minutes, so take advantage of the opportunity to grab yourself something to drink.

Once the build and deploy is complete, the CLI will report back the URLs assigned to your project. While I know it’s exciting, we’re not quite ready to visit our site. We have a few remaining tasks that need to be completed.

Finish setting up Twill

While we added Twill as a dependency earlier, we still haven’t installed it. To do so, we still need to run the twill:install Artisan command. This will:

• Create an admin.php routes file in our application’s routes directory. This is where we will declare our own admin console routes.
• Migrate the database with Twill’s migrations.
• Publish Twill’s configuration files to our application’s config directory.
• Publish Twill’s assets for the admin console UI.
• Prompt us to create a superadmin user.

However, before we can run the command, we need to make sure Twill can communicate with our database. We could use a local development environment like ddev, a docker container, or Laravel Homestead. Since this is a brand new project, we can instead connect directly to our database container using a tunnel! This will expose local endpoints for our database service that allows Twill to connect to the database exactly as it will in the application container.

From the command line:

upsun tunnel:open

Make sure to follow the directions at the end and export the PLATFORM_RELATIONSHIPS environment variable:

export PLATFORM_RELATIONSHIPS="$(platform tunnel:info --encode)"

The last thing we need to do before we run the install command is to reuse our .environment file to create the environment variables in our current terminal session that Twill can utilize:

source .environment

And now you can run Twill’s install command:

php artisan twill:install

Follow the prompts to create a superadmin account. Once it is finished, the TWill install will have created several new files, and a few directories of files that we’ll need to add to our repository:

• config/translatable.php
• config/twill.php
• public/.gitkeep
• public/assets/*
• resources/views/site/*
• routes/twill.php

Once you git add all the above and git commit, you’re ready to push.

git add config/translatable.php config/twill.php public/.gitkeep routes/twill.php public/assets resources/views/site
git commit -m "adds Twill post-install files"
upsun push -y 

Once this deployment completes, you’ll be fully Up(sun) and running with Twill!

All example files

All the example files referenced in the article above are available in our Upsun Snippets repository.