In this guide, you’ll learn how to host your dotCMS headless application on AWS Amplify. We begin by creating a Next.js app using the dotCMS example, setting the foundation for your headless setup. Once your Next.js app is in place, you’ll integrate it with Amplify for hosting and continuous deployment, allowing you to leverage Amplify’s robust features to keep your app up to date.
Prerequisites
Node.js (v20 or later) and npm installed
Basic familiarity with Next.js
Access to a dotCMS instance with sample content
An AWS Amplify account for hosting and deployment
A code editor for modifying configuration files
Create the app and download our Next.js example
Create a new Next.js app using our example
npx create-next-app my-dotcms-project --example https://github.com/dotCMS/core/tree/main/examples/nextjsOpen the project in your favorite editor, I'll be using Cursor.
Create a copy of the env.local.example file and name it env.local.
cp .env.local.example .env.localFind a dotCMS auth token and add it to the env.local file.
curl -H "Content-Type:application/json" -X POST -d '
{ "user":"admin@dotcms.com", "password":"admin", "expirationDays": 10 }
' https://demo.dotcms.com/api/v1/authentication/api-tokenMake sure to replace the user password and dotcms.com with your own.
Get the token and update the env.local file with it.
Now run the app to make sure it's working.
npm run dev
And you should see the app running on http://localhost:3000.
Push to a GitHub Repository
Amplify is a tool that allows you to deploy your app to AWS. You can use amplify-cli or the Amplify Console, in this case we'll use the Amplify Console.
So if you don't have an AWS account, now is a good time to create one. Once you have your AWS account, you can login to the Amplify Console and connect your repository.
So now we need to create the repository. So go to GitHub and create a new repository.
Make sure you are login into to you github account in your browser, if you don't have a github account, you can create one at https://github.com/
Then go to https://github.com/new and create a new repository.
After creating the repository on GitHub, add it as remote and push
git remote add origin git@github.com:USERNAME/REPO-NAME.git
git branch -M main
git push -u origin main
If you go back to the repository in your GitHub account and refresh the page, you should see something like this:
What is Amplify?
AWS Amplify is a set of tools and services provided by Amazon Web Services (AWS) that helps developers build full-stack applications. It's tightly integrated with AWS services and provides:
Hosting and continuous deployment
Authentication
API management
Storage solutions
Analytics
Push notifications
The main benefit of using Amplify with AWS is that it abstracts away much of the complexity of working directly with AWS services, while still giving you the full power of AWS infrastructure. When you deploy through Amplify, your app automatically gets:
Global CDN distribution
CI/CD pipeline
HTTPS/SSL
Cache management
Custom domains support
In this case we're focusing on the hosting and continuous deployment.
So now we need to connect the repository to the Amplify Console.
But before starting you need to create an AWS account and configure. To do so go to https://aws.amazon.com/ and create an account.
Connect the repository to the Amplify Console
Go to your AWS account and search for Amplify Console.
Click on the Amplify Console and then click on the "Deploy App" button.
Now we are going to select Github for the source code of our app.
And then you need to select the branch. Amplify is going to “watch” the branch you select for new comments and every time something new gets merged it will redeploy automatically. My base is main.
The next step is to set all the special config for the Next.js if any, in our case the dotCMS Next.js example doesn't need any special configuration.
The build command is npm run build (default)
The build output directory is .next (default)
And that’s it, but if in your case you need special configuration for your build, this is the place where you will let Amplify know.
Make sure that everything is ok and Click the button “Next”. You will get the preview page:
Make sure that everything is in ok or edit if you need, and then click “Save and Deploy”.
Deploy
Here is where the Amplify magic starts to set up your environment
Then you will see the building happening.
Click in the branch to see the details.
Here is where you can see the deployment happening in real time and the logs, in short what is doing:
Pulling the code from your GitHub repository and your branch
Running npm install
Running npm run build for the production build
And if all is good it will set a temporary domain.
But the first time you will see an error.
Environmental Variables
When Amplify tried to build it needed the variables that we have in .env file but we didn’t push that file (of course we don't want to see those variables. So we need to set them up inside the Amplify UI.
So in the sidebar click in Hosting > Environmental Variables.
Now click on “Manage Variables” on the top right.
Click in Add New
Fill the key / values we have in .env file:
And save the changes.
Now go back to the deployment sections and click in “Redeploy this version”
Wait a couple of minutes (it will depend on the size of your project) and it should deploy successfully.
You site is live
Now click in the domain generated by Amplify and you should be able to see your site.
Conclusion
This guide has walked you through building your Next.js app with the dotCMS example and integrating it with AWS Amplify for hosting. By following these steps, you not only set up a scalable deployment pipeline but also streamline ongoing updates to your headless application. With your app now live on Amplify, you’re well-positioned to further optimize your deployment process and extend your app’s capabilities.
QA Section
Why is my Next.js build failing on Amplify?
Check the Amplify build logs for errors. Build failures often result from misconfigured environment variables, incompatible Node.js versions, or issues in your code. Try running npm run build locally to catch errors before deploying.
What should I do if the dotCMS API is not responding?
A: Verify that the dotCMS instance is running and accessible, and ensure the API URL and tokens are correctly set in your environment variables. Testing API endpoints locally can also help pinpoint connectivity issues.
How can I resolve issues with environment variables not being picked up?
A: Ensure all required environment variables (e.g., API tokens, dotCMS URL) are properly defined in your local setup and in the Amplify environment settings. Misconfigurations here are a common source of errors.
What if my application is not reflecting recent changes after deployment?
Confirm that the continuous deployment process is correctly set up on Amplify. Additionally, clear any caches or force a redeployment to ensure that the latest code is being served.
How do I debug integration issues with the dotCMS example in my Next.js app?
Compare your code with the dotCMS example to identify discrepancies. Use local testing and logging to isolate errors. Running npm run build locally can reveal build-time issues that might not be immediately apparent during development.