Four days, four languages, four frameworks on Platform.sh

Platform.sh
26 Feb 2019
Four Days: Day 1, Java and Brightspot CMS

Platform.sh is well-known as the premier platform for developing and delivering applications in Drupal, WordPress, Symfony, Typo3, EZ, and Magento. We’ve even partnered directly with Magento, Symfony, and EZ Systems to help them deliver their own SaaS offerings. What you may not know is how easy it is to run just about anything on Platform.sh.

Our man in Bordeaux and Director of Customer Solutions Guillaume Moigneau recently went on a spree documenting how to get four new frameworks—in four different languages—up and running on Platform.sh.

The four couldn’t be more different. A Java CMS and three popular static site generators (SSGs), written in Golang, React, and Ruby.

Today, we’ll start with Brightspot CMS. Brightspot is a full-featured, open-source web content management system (WCMS) written in Java and backed by MySQL and Solr—two services that snap in easily to any application on Platform.sh with just a few lines of configuration.

Here, we’ll get Brightspot running with Apache Tomcat, MySQL, and Solr, with a Maven build process.

As with most projects, the pattern to get the app running on Platform.sh is quite simple.

  1. Check out or download a local copy of the application.
  2. Add the requisite .platform.app.yaml, services.yaml, and routes.yaml files that define the application configuration and build process, supporting data services and routing rules, respectively.
  3. Push your local repo to Platform.sh.
  4. For you, there’s no step 4. Platform.sh takes care of containerizing your apps and services and deploying them on our grid. No CI/CD pipelines to build and manage, no Kubernetes or IaaS-specific knowledge required.

Let’s skip ahead a bit to focus on a few things that are unique about running a Java/Tomcat application on Platform.sh.

Running Tomcat

Sometimes, Java can be tricky to run on a PaaS, especially for applications that use Tomcat. But it can be done by taking advantage of Platform.sh’s ability to run multiple application containers in a single project.

We’ve put together a ready-to-run example repository for Brightspot that shows how to make it work. Let’s go through some of the key points.

The project has two application containers, tomcat and app, each in their own directory and with their own .platform.app.yaml file. The Tomcat container is just a bare Java container with a few config files. Everything else happens in the build hook. It’s a bit long, but very straightforward; it downloads Tomcat and the Tomcat MySQL connector from scratch and installs them, then adds the config files that were included in the repository. On start, then, it runs the Catalina command to start Tomcat.

That process may not be particularly fast, but that’s why it’s on its own container: it only needs to run once. On subsequent deploys as long as there are no changes to the config files or Tomcat version that container won’t be rebuilt, just paused momentarily. It can still be upgraded or tweaked at any time by simply modifying one of the provided config files and redeploying.

The user application lives in app, and contains enough information to compile the source code for the application. It doesn’t run itself, though. Instead, its build hook uses Maven to download all of the application’s dependencies locally, compile the application, and then move the Maven build cache into the application. The deploy hook, then does this:

 # Make sure we are using the local repository.
export MAVEN_OPTS="-Dmaven.repo.local=$PLATFORM_APP_DIR/.m2/repository"
mvn \
	--offline \
	-Dtomcat.username=admin \
	-Dtomcat.password=$PLATFORM_PROJECT_ENTROPY \
	-Dmaven.tomcat.url=$(./tomcat-url)/manager/text \
	tomcat7:redeploy-only

What that does is install the built application into Tomcat, over the network connection between the two containers. Tomcat fully supports that sort of runtime update. The app container also has a relationship defined to let it access Tomcat:

relationships:
    tomcat: tomcat:http

Finally, the routes.yaml file directs all incoming HTTP requests to Tomcat:

https://{default}/:
  type: upstream
  upstream: tomcat:http

The app container isn’t even used at all after deploy is completed! Tomcat itself, with a freshly updated copy of the compiled application, is responsible for serving all web requests.

Brightspot-specific configuration

Databases

We run Brightspot on top of MySQL and Solr. Two relationships are defined in the tomcat application’s .platform.app.yaml file:

    database: "mysql:mysql"
    solr: "solr4:solr"

You can find the Brightspot services configurations in tomcat/context.xml. We use the com.psddev.dari.db.AggregateDatabase storage class with two delegates: sql and solr.

Solr is configured with the Brightspot solrconfig.xml and schema.xml located in .platform/solr/. (See our Solr documentation for details.)

Example project

The example repository includes the Brightspot hello-world application from their documentation. Feel free to remove and replace it with your own source.

There’s one quirk with the way Brightspot is configured. Maven’s mvn dependency:go-offline sometimes has an issue installing transitive dependencies (those that are depended on by something our code depends on). For that reason the junit, guava, findbugs, httpcomponents, and httpclient dependencies need to be specified explicitly.

Brightspot mode

Brightspot production mode is disabled by default. You can enable it in tomcat/context.xml.

The isAutoCreateUser option is enabled by default. Feel free to change this in the same file. The editor default path is cms/.

Starting a new project

To make trying out Brightspot on Platform.sh as easy as possible, the template linked before is ready-to-run.

To begin a new project based on this template, follow these three simple steps:

  1. Clone the repository locally. You may optionally remove the origin remote or remove the .git directory and re-init the project if you want a clean history. You’ll want to commit all your local changes.

  2. Create a new project through the Platform.sh user interface, and select “Import an existing project” when prompted.

    Now you can access your newly created project.

    On the wizard, click Git remote and copy that string.

  3. Run the provided Git commands to add a Platform.sh remote, and push the code to the Platform.sh repository. It’ll look like this, which you’ll run inside your local Git repo.

    git remote add platform <project ID>@git.<region>.platform.sh:<project ID>.git
    git push platform master

That’s it! You now have a working “hello world” level project you can build on.

Accessing the project

The / path defaults to a 404; that’s normal since the example application has no default home page. Instead, go to /cms/. Until the first user is created, it will show a registration form to create the admin user, after which you’ll have access to start creating pages.

The dari debug tools are accessible at /_debug/ as long as the application is running in debug mode.

Tomorrow come back to check out the second post in our series about running Hugo, the Go-based static site generator, on Platform.sh.