--- title: Deploy from an Existing Repository description: Deploy an app from an existing repository. url: https://developers.wpengine.com/docs/headless-platform/getting-started/deploy-from-existing-repo/ image: https://developers.wpengine.com/og/docs/headless-platform/getting-started/deploy-from-existing-repo.png --- # Deploy from an Existing Repository After selecting the `Create App` button, then select the `Pull from repository` option and click `Get started`. ![Options to create a new app including Select a Blueprint or Pull from repository](https://developers.wpengine.com/_astro/new-headless-app.CSZpI-2i_2v9MHN.webp). Selecting this option brings you to Step 1 of 3, where you will: - Select your repository details. - Set up your new Headless application. - Configure your new environment. ![Create App From Repo - Step 1](https://developers.wpengine.com/_astro/create-app-from-repo-step-1.fHduHeiR_Z1oXBAS.webp). 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](https://developers.wpengine.com/docs/headless-platform/framework-guides/astro/) - [Faust.js](https://developers.wpengine.com/docs/headless-platform/framework-guides/next-js/next) - [Gatsby](https://developers.wpengine.com/docs/headless-platform/framework-guides/gatsby/) - [Next.js](https://developers.wpengine.com/docs/headless-platform/framework-guides/next-js/next) - [Nuxt](https://developers.wpengine.com/docs/headless-platform/framework-guides/nuxt/) - [Remix](https://developers.wpengine.com/docs/headless-platform/framework-guides/remix/) - [SvelteKit](https://developers.wpengine.com/docs/headless-platform/framework-guides/sveltekit/) - SolidStart - [QwikCity](https://developers.wpengine.com/docs/headless-platform/framework-guides/qwik/) 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](https://developers.wpengine.com/docs/headless-platform/platform-guides/customizing-builds/#custom-build-commands) or [custom start commands](https://developers.wpengine.com/docs/headless-platform/platform-guides/customizing-builds/#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 chosen provider to enable cloning Blueprints. 1. In the `Connect to a Git repository` section, you can select the card (or radio button) for your chosen provider only if that provider is connected to your portal account. If any provider has not yet been connected previously, its card will appear greyed out with a `Connect +` button. To connect to a provider, click the `Connect +` button and proceed to Step 2. 2. The connection page will open in a new browser tab. To proceed, grant WP Engine permission to access repositories from your chosen provider. Once the Headless Platform connects to your desired provider’s account, the connection page will close and the `Connect +` button will disappear & the card/ radio-button will now be clickable. ![Connected to provider](https://developers.wpengine.com/_astro/create-app-github-bitbucket-gitlab.Cy_zO3DU_2fpNVR.webp) ## Select the Repository, Branch & Subdirectory Now that your desired repository provider is connected & selected, it’s time to choose your repository. 1. From the list of repositories, select the one with your application’s code. If you selected GitHub as your provider but don’t see the repository you want to use, click “Manage repositories” or “Add repository” (if no GitHub repositories are visible yet). This allows the portal to access the account where your repository is located. Note: this feature is currently only available for GitHub: ![Connected to GitHub](https://developers.wpengine.com/_astro/manage-github-repositories.BCeNQGM8_Z1BxBLB.webp) 2. 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 ![Select a branch](https://developers.wpengine.com/_astro/create-app-branch-select.Bvm90p9N_Z2cSvrQ.webp) 3. 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. ![Select the subfolder](https://developers.wpengine.com/_astro/create-app-root-directory-select.CgBN0QNo_Z2tyDzC.webp) 4. Select `Next` to proceed to the WP Engine Settings page. ## Name Application & set region 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 `Next`. ![Choose a name and region](https://developers.wpengine.com/_astro/create-app-app-settings.CZWZEeUs_xHrKk.webp) ## Name First Environment & Configure Now you have reached the third and final step, where you will setup the App’s first environment. ![Choose a name and region](https://developers.wpengine.com/_astro/create-app-env-settings.ChwwtjSj_Z1em4R3.webp) ### 1. 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. ### 2. Connect WordPress Environment Every headless environment is associated with a WordPress environment. Choose either: - `I already have my 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 environment`: WP Engine makes a new WordPress site and links it to your application. In the box, enter a name for your new WordPress site. ![Link to WordPress](https://developers.wpengine.com/_astro/create-app-wordpress-select.BuF1-IiY_189Vwj.webp) ### 3. Install Headless Plugins In order for your WordPress environment to become “headless”, our Headless Platform can install the [WPGraphQL](https://wordpress.org/plugins/wp-graphql/), [Faust.js](https://wordpress.org/plugins/faustwp/) and WP Engine Atlas Headless Extension plugins. ![Install Headless Plugins](https://developers.wpengine.com/_astro/plugins-env-vars.DVGCn7Z7_Z1Pibhi.webp) ### Select `Add 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. ![Headless App Building](https://developers.wpengine.com/_astro/successful-deployment.B4Fqz9zP_89HK9.webp) ## 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! ![First app deployed](https://developers.wpengine.com/_astro/first-app-deployed.QrwsN377_Z1oscVw.webp) ## 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 helpful? Thanks for the feedback! ```json {"@context":"https://schema.org","@graph":[{"@type":"WebSite","@id":"https://developers.wpengine.com/#website","name":"WP Engine Product Documentation","url":"https://developers.wpengine.com/","description":"Resources for developing, deploying, and scaling on WP Engine.","inLanguage":"en-US","keywords":["API documentation","product documentation","headless WordPress","managed WordPress hosting"],"publisher":{"@id":"https://wpengine.com/#organization"}}]} ```