Dev Docs

# Infrastructure & Tech

# Technology Overview

Most Classic projects share a similar tech stack with some variations.

  • PHP 7.4
  • WordPress with Advanced Custom Fields. Using a modified Bedrock (opens new window) template.
  • Node 12 - 14
  • Composer
  • Yarn/Npm
  • SCSS
  • jQuery (Legacy)
  • React - for complex UI features such as Interactive Maps.
  • Webpack / Babel / Eslint / Stylelint / Prettier for code quality tools.
  • Nginx for local hosting (trough Valet (opens new window)) and for production hosting
  • MySQL

For sites hosted by Sideways, we use:

  • AWS EC2/Elastic Beanstalk/RDS/SES/Pipelines/CodeBuild
  • CloudFront as SSL termination and full site delivery
  • S3 for storing assets

# Hosting Overview

Classic projects are almost always hosted in Sideways' own AWS instance. When they are, this diagram applies:

  • CloudFront is deployed on top of S3 and ElasticBeanstalk, acting as SSL terminator.
  • All assets are stored in S3 exclusively
  • All outgoing transactional emails uses AWS SES for delivery using no-reply@sideways-nyc.com as the sender.

Projects not hosted in-house vary greatly depending on client needs, please refer to each project's README file for more information.

# Environment setup

  • During development, an staging environment is created in classic-infra (opens new window) for each site, deploying:
    • An ElasticBeanstalk application and environment
    • One instance of CloudFront, S3, Code Build and Code Pipeline
  • The staging environment follows the [reponame]-stage.sidewaysdigital.com URL convention
  • The staging environment is behind HTTPS, we use a shared certificate for *.sidewaysdigital.com on all staging sites.
  • There is a development and a production RDS instance that most sites share, we only deploy new RDS instances for larger clients
  • Environments come pre-configured with environment variables for database credentials and IAM Role keys to access AWS services.

# CI/CD

  • Each PR and commit to the master branch is tested locally using GitHub Pipelines. For most projects this just means running the linters (ESLint / Stylelint) and doing a full frontend build.
  • Each commit to the master branch of a project automatically builds and deploys that version to the staging environment
  • Once production is deployed, every push to the production branch builds and deploys that version to the production environment

# File system considerations

It is important to note that deployed environments do not use a shared file system, and due to the way Elastic Beanstalk works, every deploy to any environment completely wipes the previous version (and all of it cached files) from existence, which means:

  • Code can't depend on persisting files to disk for any other purpose other than caching
    • Even this is risky if the site is going to be load balanced, as you can't correctly invalidate the cache if it is partitioned across different hosts. Fortunately, we almost always use a single EC2 instance per website.
  • Each time we deploy, the file cache is invalidated "for free", so we don't need to do anything else to clear the cache.
  • All WordPress plugins must be vetted to ensure they don't do weird things where they store the settings in the FS or do otherwise tricky things with the file system.
  • All assets are stored in S3, so code that processes files in batches (importing from instagram, regenerating thumbnails) tends to be a bit slower and require correct error handling and retry logic

# Production

Deploying a full CloudFront instance for each staging sites is a bit wasteful, it introduces some complexity during development but on the other side we get almost no differences between staging and production environments.

Apart from some PHP debug settings, the most glaring difference is that one or more SSL certificates are deployed once a production environment is launched. This is almost always done via AWS ACM. See Production Deployment for more details.

# Folder structure

From the root of the sw-classic-skeleton (opens new window) V2:

  • .ebextensions/ - AWS ElasticBeanstalk configuration (opens new window). It is used for setting PHP.ini variables.
  • .github/ - GitHub specific stuff such as Workflows and PR templates.
  • .platform/ - Elastic Beanstalk extensions for linux platforms (opens new window). It is used to override the nginx.conf for better security and compatibility with WordPress.
  • config/ - Alternative to wp-config.php for storing configuration across environments (see Bedrock Configuration (opens new window)).
  • vendor/ - Composer output directory for non-WP-Plugin dependencies
  • web/ - The public document root directory in Nginx. WordPress, WP Plugins and the site's theme live here.
  • .env.example - Once copied to .env, local environment variables (only used during development)
  • buildspec.yml - The build script used by CodeBuild (opens new window) during CI/CD. Keep in mind that only the files listed in this file are deployed to ElasticBeanstalk, so if you need to deploy some new file or folder don't forget to add it here.
  • phpcs.xml - Linting rules for PHP
  • wp-cli.yml - WP-CLI settings so that it knows where to find our WP installation
  • composer.json - Composer dependencies. WordPress, its plugins and other third party libraries are installed exclusively through Composer.
  • composer.lock -
  • .gitignore
  • README.md -

# Redirects from a previous website

When developing a replacement of an existing site (as in, you are creating a new website for an existing domain). It is very important to create a redirect map of old to new urls, to preserve SEO and pre-existing links to the site.

To do this in Classic V2 sites, you need to add these redirects as nginx redirection rules. See Lightstone redirects (opens new window) as an example.

← Sideways Toolbox →