Developer Documentation

Getting Started

This guide covers getting started with a brand new Altis project.

After reading this guide, you'll know:

  • How to start a new Altis project
  • How to run your Altis project locally
  • The layout of an Altis project

Core concepts in Altis

Before you get started, it's important to be aware of a few core concepts which affect how you think about and build sites for Altis.

With Altis, you will work on a project. This encompasses the codebase and the hosting provided by Altis Cloud. Each project can have multiple sites, which can represent multiple domains, subdomains, or other distinct websites. Sites within a single project share a common codebase, but can have different customizations applied to each site.

Custom functionality on top of the Altis platform is implemented via plugins. Each major feature generally has a separate plugin, and these can be enabled or disabled for each site. They can also be enabled across the entire project.

Design and styling of sites is implemented via themes. Projects can contain many themes, and each site has a single theme active. Themes can be shared across sites, or used on only a single site.

Creating a new Altis project

The quickest way to get started with Altis is to use Composer. If you don't already have Composer, follow the Composer installation guide.

To get started, run:

composer create-project altis/skeleton my-project

Note: You must have Composer v1.5 or newer. Run composer self-update to ensure you're using the latest version.

Follow the interactive prompts to get started.

This will create a new directory called my-project, set up the project, and install the Composer dependencies. This directory is now ready for you to start working on your project.

Your project's layout

Your project directory will contain a number of autogenerated files and directories.

  • composer.json and composer.lock - These files allow you to specify the dependencies for your project. These files are used by Composer.
  • content/ - Contains all the functional code that makes up your project.
    • mu-plugins/ - Contains any custom modules for your project.
    • plugins/ - Contains WordPress plugins which can be activated on a per-site basis.
    • themes/ - Contains the available themes for your project.
  • index.php - The main entrypoint used by Altis. Don't edit this file.
  • vendor/ - Contains the third-party dependencies for your project, including Altis.
  • wordpress/ - Contains WordPress, the core CMS used by Altis.
  • wp-config.php - The main configuration used by Altis. Don't edit this file.

Generally, you'll be mostly working on files inside the content directory. This directory contains most of your project-specific code, including new functionality (in the form of "plugins") and visual styling (in the form of "themes").

To start using your project, you'll need to set up a development environment.

Running your project locally

For local development, you'll also need to add a local server to your development dependencies. Altis includes a Docker based development environment out-of-the-box. See the Local Server documentation for more details.

Local Server requires Docker Desktop for Mac or Windows, or Docker Engine on Linux.

If you are unable to run Docker Desktop or Docker Engine on your machine you can use the alternative local development environment based on Chassis. Chassis requires Vagrant and VirtualBox.

To set up Local Server for Altis, run the following inside your project's directory:

composer serve

This will download and start all the services needed for Altis development.

The first time you run Local Server, it may take a little longer than usual, as it downloads the containers. Once this is complete, you will now have a working local site at https://my-project.altis.dev/. Visit /wp-admin/ and login with admin / password to get started!

If you used a directory name other than my-project the default URL will be https://<directory name>.altis.dev.

To stop Local Server, run composer server stop.

To start the virtual machine again run composer serve.

Ready for development!

When you first view your local site, you'll see the Altis splash page. This indicates that the site has been set up, and is awaiting your custom code.

To get started with development, you can start working on your first theme to change the visual style of your project.