Upsun User Documentation

Deploy Next.js on Upsun

Sign up

Get your free trial by clicking the link below.

Get your Upsun free trial

Before you begin Anchor to this heading

You need:

  • Git. Git is the primary tool to manage everything your app needs to run. Push commits to deploy changes and control configuration through YAML files. These files describe your infrastructure, making it transparent and version-controlled.
  • A Upsun account. If you don’t already have one, register for a trial account. You can sign up with an email address or an existing GitHub, Bitbucket, or Google account. If you choose one of these accounts, you can set a password for your Upsun account later.
  • The Upsun CLI. This lets you interact with your project from the command line. You can also do most things through the Web Console.

1. Create a Next.js app Anchor to this heading

To create your Next.js app, follow these steps.

  1. Follow the Next.js installation guide. To fast track the process, run the following commands:

    npx create-next-app@latest
  2. To initialize the local Git repository and commit local files, run the following commands:

    cd my-app
    git init
    git add .
    git commit -m "Init Next.js application."

2. Create a new project Anchor to this heading

To create a project on Upsun, follow these steps.

To create a new project with the Upsun CLI, use the following command and follow the prompts:

upsun project:create
  1. Create an organization or select an existing one.

  2. Click Create from scratch.

  3. Fill in details like the project name and region.

  1. To link your local source code to your new Upsun project, run the following command:

    upsun project:set-remote <projectId>

    This command adds a new remote called upsun to your local Git repository, which is equivalent to the following commands:

    git remote

    It also creates a new .upsun/local/project.yaml file that contains the <projectId> for the upsun CLI to use.

3. Choose your Git workflow Anchor to this heading

You can use Upsun projects as a classic Git repository, where you are able to push your source code in different ways, using either the Git CLI or the Upsun CLI. You can choose which way —or Git workflow— you want to use for your project from the following options:

  • Your project source code is hosted on a Upsun Git repository
  • Your project source code is hosted on your own GitHub repository
For the rest of this guide, you will use the normal Git workflow (git add . && git commit -m "message" && git push upsun) to commit your source code changes to Git history. You will also use the Upsun CLI to deploy your Upsun environment with the latest code updates.

Upsun provides a Github integration that allows your Upsun project to be fully integrated with your Github repository. This enables you, as a developer, to use a normal Git workflow (git add . && git commit -m "message" && git push) to deploy your environment—with no need to connect to the Upsun Console.

4. Configure your project Anchor to this heading

To host your Next.js application on Upsun, you need to have a few YAML configuration files at the root of your project. These files manage your app’s behavior. They are located in a .upsun/ folder at the root of your source code and structured in a similar way to this:

├── .upsun
│   └── config.yaml
├── [.environment]
└── <project sources>

To generate these files, run the following command at the root of your project:

upsun project:init

Follow the prompts.

       type: "nodejs:20"
          build: |
             set -eux
             npm run build             
             start: npm run start -- -p $PORT

As an example, above is the minimum configuration needed to deploy a Next.js application on Upsun without any services. Depending on your answers to the prompts, you may also have relationships and services defined.

To commit your new files, run the following commands:

git add .
git commit -m "Add Upsun config files"

5. Deploy Anchor to this heading

And just like that, it’s time to deploy!

Depending on the Git workflow you chose at the beginning of this tutorial, there are two ways to deploy your source code changes.

You can push your code using the normal Git workflow (git add . && git commit -m "message" && git push). This pushes your source code changes to your upsun remote repository. Alternatively, you can use the following Upsun CLI command:

upsun push

When you choose to use a third-party Git hosting service, the Upsun Git repository becomes a read-only mirror of the third-party repository. All your changes take place in the third-party repository.

Add an integration to your existing third-party repository:

If you are using an integration, on each code updates, use the normal Git workflow (git add . && git commit -m "message" && git push) to push your code to your external repository. To do so, run the following command:

git push origin

Your GitHub, GitLab, or Bibucket integration process then automatically deploys changes to your environment. If you’re pushing a new Git branch, a new environment is created.

Upsun then reads your configuration files, and deploys your project using default container resources. If you don’t want to use those default resources, define your own resource initialization strategy, or amend those default container resources after your project is deployed.

Et voilà, your Next.js application is live!

6. Make changes to your project Anchor to this heading

Now that your project is deployed, you can start making changes to it. For example, you might want to fix a bug or add a new feature.

In your project, the main branch always represents the production environment. Other branches are for developing new features, fixing bugs, or updating the infrastructure.

To make changes to your project, follow these steps:

  1. Create a new environment (a Git branch) to make changes without impacting production:

    upsun branch feat-a

    This command creates a new local feat-a Git branch based on the main Git branch, and activates a related environment on Upsun. The new environment inherits the data (service data and assets) of its parent environment (the production environment here).

  2. Make changes to your project. For example, edit the views/index.jade file and make the following changes:

    diff --git a/views/index.jade b/views/index.jade
    index 3d63b9a..77aee43 100644
    --- a/views/index.jade
    +++ b/views/index.jade
    @@ -2,4 +2,4 @@ extends layout
     block content
       h1= title
    -  p Welcome to #{title}
    +  p Welcome to #{title} on Upsun
  3. Commit your changes:

    git add views/index.jade
    git commit -m "Update index page view."
  4. Deploy your changes to the feat-a environment:

    upsun push
  5. Iterate by changing the code, committing, and deploying. When satisfied with your changes, merge them to the main branch, and remove the feature branch:

    upsun merge
        Are you sure you want to merge feat-a into its parent, main? [Y/n] y
    upsun checkout main
    git pull upsun main
    upsun environment:delete feat-a
    git fetch --prune

    Note that deploying to production is fast because the image built for the feat-a environment is reused.

    For a long running branch, to keep the code up-to-date with the main branch, use git merge main or git rebase main. You can also keep the data in sync with the production environment by using upsun env:sync.

Further resources Anchor to this heading

Documentation Anchor to this heading

Community content Anchor to this heading

Blogs Anchor to this heading

Is this page helpful?