Deploy from an Existing Repository

Once you have selected the Create App button, then select the Pull from repo option and Continue.

Now that you have chosen to deploy from an existing repository, you can select the repository and deploy it to our Headless Platform. Pushing code changes to the branch of your choice in your repository will then deploy updates to our Headless Platform automatically.

Prepare Your App for Deployment

The Headless Platform supports Node.js applications using many popular frameworks with minimal configuration. You can view our framework guides to see what may be required of your particular framework:

• Astro
• Faust.js
• Gatsby
• Next.js
• Nuxt
• Remix
• SvelteKit
• SolidStart
• QwikCity

Some newer frameworks may not have a framework guide yet, but can still run on our Headless Platform using whatever Node.js-based adapters are provided by the framework or as SSG using a Node.js package to serve static assets like http-server or express.

Custom build and start commands

By default, the Headless Platform will run npm run build and npm run start to build and start your application. If you want to run different commands to build or start your application, you can reference the docs on custom build commands or custom start commands to review the various ways this can be implemented.

Using the correct port

The platform expects your application to listen for traffic on one of the following ports: 8080(default) or 3000. You may receive an error during deployment if your application is using a different port value. In some frameworks, you may be able to use an environment variable named PORT to specify which port you application will listen on.

Connect to a Supported Repository Provider

Our Headless Platform supports three repository hosting service providers - GitHub, Bitbucket and GitLab. Connect to your repository provider, then choose the account/ namespace, in order to find the repository you wish to deploy on our Headless Platform.

1. In the Connect to repository section, select Connect under the provider you want to connect with.

2. GitHub, Bitbucket or GitLab opens in another tab of your web browser. Give WP Engine permission to access your repositories.

After the Headless Platform connects to your account, the Connected label with green checkmark indicates that you are connected. A list of repositories associated with your account appears.

Select the Repository & set region

Now that you are connected to the provider of your choice, it’s time to connect your repository.

1. From the list of repositories, select the one with your application’s code.

   If you have selected GitHub as your provider but don’t see the repository which you’d like to use, click on “Manage GitHub repositories” or “Add GitHub repository” (if no GitHub repositories visible yet) button presented, as the account where the repository resides is not visible yet to Portal (this is a GitHub only feature at present):

   

2. Select Continue to proceed to the WP Engine Settings page.

Name Application

On the WP Engine Settings screen:

1. Fill out a name for your application. We recommend choosing a name similar to your repository’s name. The application name cannot be changed once it has been deployed.

2. Select a region for your application. The region you select will be used for all of your app’s environments (production/staging/etc.) and cannot be changed once your application has been deployed.

3. Click Continue.

Configure the Environment

Select a Branch

From the list of your repository’s branches, select the branch you want to base your environment on. Whenever changes are pushed to this branch, your app will be automatically re-deployed.

Examples:

• If you want to create a production environment, you could use your repo’s main branch
• If you want to create a staging environment, you could use your repository’s staging branch

Verify Your Project Directory

If your project is stored in a folder within your repository, specify the path to your root folder by clicking on the Edit icon in the Root Directory field.

Name Your Environment

Enter a name for your environment. The name should represent how you intend to use the environment. For example, enter something like prod if it’s a production environment, staging if it’s a staging environment, etc.

Connect WordPress Environment

Every headless environment is associated with a WordPress environment. Choose either:

• I already have a WordPress environment: Use a WordPress site from your WP Engine account. Select the search bar and search for the name of your WordPress site.
• I want to create a new WordPress install: WP Engine makes a new WordPress site and links it to your application. In the box, enter a name for your new WordPress site.

Install Headless Plugins

In order for your WordPress environment to become “headless”, our Headless Platform can install the WPGraphQL, Faust.js and WP Engine Atlas Headless Extension plugins.

Select Create App.

The app’s Environment Details page appears upon completion of the app create steps. When the Headless Platform completes the build step of your headless app’s default environment, a checkmark & status message of success appears in the Last deployment card.

View Your App

To visit your headless WordPress app once the first deploy finishes, click the link under the Atlas URL heading. Your app opens in a new browser tab. Enjoy!

Set Environment Variables (Optional)

To add environment variables for your app, click Go to Variables.

Enter the Key and Value pairs for each environment variable.

For example, you may need to add a NEXT_PUBLIC_WORDPRESS_URL key with a URL as its value to specify which WordPress site should be used as the data source for the app. You may also need to specify additional environment variables to store sensitive data such as API keys and secrets.

Please refer to your JavaScript framework’s documentation if you’re unsure what environment variables are required for your app.

Was this page helpful?

👍 Yes  |  👎 No