DEV Community: Geoff B.

How to deploy a Next.js application to GitLab Page

Geoff B. — Fri, 19 Apr 2024 10:05:04 +0000

Next.js has become a standard choice for developing React applications, offering various deployment options across different platforms. While Vercel is a popular choice for building and deployment, specific project requirements may require deployment to GitLab. In this guide, I'll illustrate the process of deploying a Next.js application to GitLab Pages.

GitLab Pages allows you to publish a static website directly from a repository. In this tutorial, we'll create a pipeline that generates a static export of a Next.js application and publishes it automatically after each commit. Let's start by creating a simple Next.js application.

Create a Next.js application

For this project I will be using the current LTS version of Node.js (v20.12.2), both locally and in the pipeline. It is important to keep this version consistent throughout the whole process to ensure that the features used locally will also work in the pipeline.

To create a new Next.js application, we need to run this command:

npx create-next-app@latest

You will be prompted to answer a few questions to select the configuration that suits you best. Personally, I opted for TypeScript, ESLint, Tailwind CSS and the App Router. Additionally I installed shadcn/ui for the button component and Prettier for a consistent code formatting. While the application itself isn't the primary focus, I created two pages to showcase routing and included an image for asset management.

Now, it is essential to create a new GitLab repository to store our newly created application before jumping into the export and deployment.

Setup a new gitlab repo

For this project, I will be creating a public repository where my Next.js application will be versioned.

Once completed, we can proceed to link our Next.js application with the new repository. To achieve this, navigate to the directory of the application and initialize Git.

git init --initial-branch=main

git remote add origin git@gitlab.com:geoffb/deploy-nextjs-app-with-gitlab.git

After this setup is done, we can make our initial commit to push the entire application to the repository. You can access the application here: https://gitlab.com/geoffb/deploy-nextjs-app-with-gitlab

The only remaining task is to adjust the configuration of the Next.js application for static export and create a pipeline file to publish the website.

Create a static export and publish it!

In the Next.js documentation it states that:

Next.js enables starting as a static site or Single-Page Application (SPA), then later optionally upgrading to use features that require a server.

When running next build, Next.js generates an HTML file per route. By breaking a strict SPA into individual HTML files, Next.js can avoid loading unnecessary JavaScript code on the client-side, reducing the bundle size and enabling faster page loads.

Since Next.js supports this static export, it can be deployed and hosted on any web server that can serve HTML/CSS/JS static assets.

To build a static export you will need to edit the next.config.mjs and add this few lines:

/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    unoptimized: true,
  },
  output: 'export',
}

export default nextConfig

output: specify that we will do a static export
images/unoptimized: will serve the images as they are instead of being optimized by the next/image component. https://nextjs.org/docs/app/api-reference/components/image#unoptimized

Now that our application is ready to be built as a static site, we need to tell GitLab what to publish. To accomplish this, let's create a new file named .gitlab-ci.yml at the root of our repository.

image: node:20.12.2-alpine3.19

stages:
  - build

pages:
  stage: build
  script:
    - npm install
    - npm run build
  artifacts:
    paths:
      - out
  publish: out
  only:
    - main

The first line specifies the Docker image to be used for executing the job within the pipeline. It's worth noting that I've opted for the same node version as previously specified, matching my local environment.

This pipeline currently consists of only one stage, the build stage. You have the flexibility to incorporate additional stages, such as a linting stage, according to your requirements.

The pages keyword tells the pipeline to upload the result of the job to the GitLab Pages. In this block of code we need to specify a few things:

stage: indicating the stage in which the job should run
script: the different commands to execute. To generate a static export of the Next.js application we only need to install the dependencies and build it.
artifacts: correspond to the output of the job, it is a list of files and directories. When exporting a Next.js application, the default output directory is typically named out (this can be configured in the next.config.mjs file).
publish: to use a different content directory other than the default public directory.
only: specifying to execute the pipeline on our current branch main

After committing the changes to both the next.config.mjs and the new .gitlab-ci.yml file, a pipeline will be automatically executed as you can see below:

The pipeline will execute the jobs within the stages. In this scenario, we have a straightforward pipeline with one job in one stage. This job will generate a static export of the Next.js application, which will then be automatically published to GitLab Pages. Once everything is done we can see that then pipeline succeeded:

Feel free to access the static website and explore its functionality by following this link. You can test navigation between the two pages and view the image asset. https://deploy-nextjs-app-with-gitlab-geoffb-985ba1d87bd969f03ee8f4e83b.gitlab.io/

In conclusion, we can say that Next.js provides a range of deployment solutions across diverse platforms. Throughout this guide, we've explored the steps involved in deploying a Next.js application to GitLab Pages, which includes many interesting topics that can be explored and expended.

Managing local resources with Tilt or how do I setup my local dev environment

Geoff B. — Wed, 27 Jan 2021 19:58:27 +0000

I have been working with Tilt for almost a year now and I find it very useful to manage local resources and applications. I'm currently working on a side project called flashcards and I have done the setup of my local environment with Tilt.

What we want to achieve here is to setup:

A local database running in a container
A bare Phoenix project (API)
A bare React project
A Tiltfile to rule them all

Here is the tree of my directory:

├── backend
├── docker
│   └── docker-compose.yml
├── env
│   └── postgres.env
├── frontend
└── Tiltfile

Setup the database

Prerequisite:

Have Docker installed and running

First let's setup the docker-compose.yml file. I want to have a simple postgres database running in a docker container.

version: '3.8'
services:
  postgres:
    image: postgres:13
    container_name: flashcards_database
    volumes:
      - postgres-data:/var/lib/postgresql/data/
    env_file:
      - ../env/postgres.env
    ports:
      - 5432:5432

volumes:
  postgres-data:

Nothing out of the ordinary here, the only thing I like to do is having the environment variables in an external file.

POSTGRES_USER=geoffroy_baumier
POSTGRES_PASSWORD=password
POSTGRES_DB=flashcards_dev

Perfect, now that this is done I can spin it up in order to setup my Phoenix project.

$ docker-compose -f docker/docker-compose.yml up
[...]
Creating fashcards_database ... done
Attaching to fashcards_database
[...]
fashcards_database | 2021-01-27 18:18:23.825 UTC [1] LOG:  database system is ready to accept connections

The database is now listening on the port default postgres port 5432.

Setup the API

Prerequisites:

Have erlang installed
Have elixir installed
And have the database running

"If we have just installed Elixir for the first time, we will need to install the Hex package manager as well. Hex is necessary to get a Phoenix app running (by installing dependencies) and to install any extra."
Source: hexdocs.pm

Let's install the hex package manager:

$ mix local.hex

Now let's install the Phoenix application generator:

$ mix archive.install hex phx_new

I only want to create an API and not use the views in Phoenix. So I do not want to generate the project with views and use webpack. I will use the corresponding options (for more info see here):

mix phx.new flashcards --no-html --no-webpack

Fetch and install dependencies? [Yn] y
    * running mix deps.get
  * running mix deps.compile

Now that our project is generated we can edit the database configuration in config/dev.exs:

# Configure your database
config :flashcards, Flashcards.Repo,
  username: "geoffroy_baumier",
  password: "password",
  database: "flashcards_dev",
  hostname: "localhost",
  [...]

Now we can create the database:

$ mix ecto.create
Compiling 11 files (.ex)
Generated flashcards app
The database for Flashcards.Repo has already been created

Good, now let's start the application:

$ mix phx.server
[info] Running FlashcardsWeb.Endpoint with cowboy 2.8.0 at 0.0.0.0:4000 (http)
[info] Access FlashcardsWeb.Endpoint at http://localhost:4000

Perfect! If you want to see the project running, go to http://localhost:4000/dashboard/home.

Setup the frontend

Prerequisites:

Have NodeJS installed
Choose a package manager, personally I use yarn

Now we have our database and our API. As you see they already take two tabs of my terminal (dramatic tone, I could also just run in detached mode). We are only missing the frontend, let's jump into it without many details (more info here).

$ yarn create react-app my-app
$ yarn start

Now the frontend is running on http://localhost:3000/. And a third tab in my terminal is being used!

Setup Tilt

Here come the best part, we can regroup and manage those resources all in one place using Tilt. Thanks to Tilt we can automate processes: start of the applications, watch for file changes, build our containers, watch the logs,...

If you are using Homebrew you can install Tilt with this command:

$ brew install tilt-dev/tap/tilt

For the magic to happen, I strongly suggest that you stop your container (even delete it), stop the Phoenix application and also the React application. Stop everything!

Now let's create our Tiltfile at the root of the project.

The first thing we want to do is create and start our database container. All I have to is reference the docker-compose file:

docker_compose('docker/docker-compose.yml')

Then just below let's add our Phoenix application, I will call it 'api':

local_resource(
  'api',
  'cd backend && mix deps.get',
  deps=['backend/config', 'backend/mix.exs', 'backend/mix.lock'],
  serve_cmd='cd backend && mix phx.server',
  resource_deps=['postgres']
)

Let's go through the list of these parameters:

The first one is the name
Then it is the command to be executed
After we find the deps: which is "a list of files or directories to be added as dependencies to this cmd. Tilt will watch those files and will run the cmd when they change."
Then we have the serve command which will be run on update
And finally the resources of which this current resource depends on. As you can see we can directly reference the docker service.

There are more parameters available: link

And finally we can add our frontend:

local_resource(
  'frontend',
  'cd frontend && yarn install --frozen-lockfile',
  serve_cmd='cd frontend && yarn start',
  deps=['frontend/package.json', 'frontend/yarn.lock'],
  resource_deps=['api']
)

Here is the whole Tiltfile:

docker_compose('docker/docker-compose.yml')

local_resource(
  'api',
  'cd backend && mix deps.get',
  serve_cmd='cd backend && mix phx.server',
  deps=['backend/config', 'backend/mix.exs', 'backend/mix.lock'],
  resource_deps=['postgres']
)

local_resource(
  'frontend',
  'cd frontend && yarn install --frozen-lockfile',
  serve_cmd='cd frontend && yarn start',
  deps=['frontend/package.json', 'frontend/yarn.lock'],
  resource_deps=['api']
)

To run it we simply have to run this command in the root of our directory:

$ tilt up

And everything spins up and we have a nice interface to manage every individual service just in one place. I think that it's wonderful and I gladly recommand using it for local developement. It makes everything easier to start the whole stack with just one command. It also watches the files and does a reload. You can also manually reload a resource. And you have access to all the logs in one tab!

Ho I almost forgot, to stop it you can run:

$ tilt down

More info on managing local resources here.

Upgrading postgreSQL with Homebrew

Geoff B. — Tue, 26 Jan 2021 21:01:11 +0000

After upgrading a few programs including postgres when starting a new project, I ran into an issue. I already had some postgres databases from older projects and I couldn't start postgres (and create my new database).

To install postgres with brew I used:

$ brew install postgres

To see if postgres is running I can type:

$ brew services 
Name       Status  User Plist
postgresql stopped

Then the funny thing was when I tried to start the service:

$ brew services start postgres
==> Successfully started `postgresql` (label: homebrew.mxcl.postgresql)

Great! So it's running! But no..

$ brew services
Name       Status  User             Plist
postgresql error   geoffroy_baumier /Users/geoffroy_baumier/Library/LaunchAgents/homebrew.mxcl.postgresql.plist

To see what is the issue, let's look at the logs:

$ tail /usr/local/var/log/postgres.log
2021-01-26 21:12:47.678 CET [8757] FATAL:  database files are incompatible with server
2021-01-26 21:12:47.678 CET [8757] DETAIL:  The data directory was initialized by PostgreSQL version 12, which is not compatible with this version 13.1.

And there was the issue.

All I had to do to fix this was to run this command:

$ brew postgresql-upgrade-database

Then let's start it postgres:

$ brew services start postgres
==> Successfully started `postgresql` (label: homebrew.mxcl.postgresql)

$ brew services
Name          Status  User             Plist
postgresql    started geoffroy_baumier /Users/geoffroy_baumier/Library/LaunchAgents/homebrew.mxcl.postgresql.plist
postgresql@12 stopped

No I can see that I have two postgres services with the two different versions. I can create my new updated database. Also the good thing is that I didn't lose any data from previous project and I can run the service with version 12 if I ever need it.