[삽질로그] Heroku로 Strapi(with PostgreSQL) 배포하기 1/2

이 글은 Heroku Free tier를 사용하여 호스팅하기 위한 튜토리얼인데 2022년 11월 28일자로 Heroku에서 Free tier를 제공하지 않기 때문에 무료 배포를 하기 원하는 분들은 다른 튜토리얼들을 참고해보길 바란다. 

(이 글은 2021년 4월 14일 기준 글이다.)

🤨 삽질의 발단

지난달에 새로운 사이드 프로젝트를 시작했다. 프론트는 Next.js를 사용하였고 백엔드는 Github에 json파일을 올려 gh-pages로 호스팅을 한 정석이 아닌(?) 루트를 사용했다. 프로젝트를 대략 완성하기는 했지만 백엔드가 영... 너무 찜찜했다.
돈은 들이기 싫고, API는 만들고 싶고, 이것저것 찾아보다 알게 된 Strapi!
COMMUNITY PLAN은 무료라기에 튜토리얼을 찾아서 바로 설치했다. 사실 설치한지는 벌써 3주 전?이니 시간이 그래도 흘렀지만... Strapi를 처음 만나고도 약간의 우여곡절이 있었다. (우여곡절은 생략한다.) 무튼 그러다 어제 제대로 각잡고 앉아서 배포까지 끝내버리리 결심하고 진짜 끝냈다.
왜 매번 설정하는 건 이렇게도 힘들고 삽질을 해야만 하는지... 내가 너무 모르는 게 많아서라고 생각했었는데 아는 개발자 분께 한번 여쭤보니 본인도 그러시단다... 그래서 기록해둬야 한다고... (위로가 됐다.)
혹시 Strapi를 또 사용할 미래의 나를 위해 이 글을 작성한다. 혹 이 글이 다른 분께도 도움이 된다면.... (더 큰 시련을 안겨드리지 않는 것만으로도) 좋겠다.

🛠 준비사항

• Heroku 계정 생성 (https://www.heroku.com)
• Heroku CLI 설치 (Heroku 공식 문서 참고) 
• PostgreSQL 설치 (PostgreSQL 공식 사이트 참고)

Strapi 공식 문서 참고

Heroku

🚀 시작

1. Heroku 로그인하기 (준비사항이 모두 준비 되어있어야한다.) 

heroku login

위의 명령어를 터미널에 입력하면 브라우저로 Heroku Login 화면이 뜨고 Login 버튼을 클릭한다. 성공적으로 로그인되면 터미널의 Heroku CLI에서 아래와 같이 확인할 수 있다. 

Logged in as <내 계정 이메일>

 

2. PostgreSQL 로컬 데이터베이스 생성하기

새로운 터미널 창을 하나 띄워서 아래와 같이 순차적으로 실행한다. 

# 1. postgres 실행
psql postgres

# 2. 데이터베이스 생성
CREATE DATABASE <데이터베이스 명>;

# 3. User role 생성
CREATE ROLE <데이터베이스 사용자명> WITH LOGIN PASSWORD '<패스워드>' CREATEDB;

# 4. 권한 부여
GRANT ALL PRIVILEGES ON DATABASE <데이터베이스 명> TO <데이터베이스 사용자명>;

데이터베이스 명, 사용자명, 패스워드가 Strapi 프로젝트 생성 시 필요하니 기억해둘 것! Heroku 로그인이 되어 있는 창으로 돌아간다. 

 

3. Strapi 프로젝트 생성하기

터미널에서 프로젝트를 생성하고 싶은 폴더로 이동한다. 예를 들어 "test-api"라는 Strapi 프로젝트를 "sideproject" 폴더 아래에 생성하고 싶다면, "sideproject" 폴더로 이동하여 아래의 명령어를 입력한다. yarn/npx 사용하는 것에 맞춰 둘 중 하나를 입력한다.  

# yarn
yarn create strapi-app <프로젝트 이름>

#npx
npx create-strapi-app <프로젝트 이름>

위의 명령어에서 --quickstart라는 플래그를 맨 뒤에 붙이면 로컬에서는 SQLite 데이터베이스를 사용하여 프로젝트를 생성하는데 Heroku에서는 호환되지 않는다고 한다. --quickstart를 사용하여 생성해준 프로젝트는 나중에 Heroku에서 데이터베이스를 따로 설정해주어야 하기 때문에 --quickstart라는 플래그 없이 프로젝트를 생성해주었다. 

--quickstart를 입력해주지 않아도 위의 명령어를 입력하면 아래와 같이 보인다.

? Choose your installation type (Use arrow keys)
  Quickstart (recommended)
> Custom (manual settings)

화살표 키로 Custom으로 이동 후 선택해주면(엔터키) 아래와 같이 데이터베이스를 선택할 수 있다. 

? Choose your default database client (Use arrow keys)
  sqlite
> postgres
  mysql
  mongo

위와 같이 화살표 키로 postgres로 이동 후 선택해주면(엔터키) 아래와 같이 전 단계에서 생성해준 postgres 데이터베이스 정보를 입력해야 한다. 

? Database name: <데이터베이스 명>
? Host: (127.0.0.1)				# 엔터치고 넘어감
? Port: (5432) 					# 엔터치고 넘어감
? Username: <데이터베이스 사용자명>
? Password: <패스워드>
? Enable SSL connection: N			# N 입력, y는 설정이 따로 필요한듯...

기다리면 프로젝트 생성을 시작하고 설정하는데 시간이 약간 걸린다. 생성이 완료되면 생성된 프로젝트 폴더로 이동해서 yarn develop/start/build 명령어로 로컬로 돌릴 수 있지만 Heroku에 배포하는 것이 목표이기 때문에 다음 단계로 진행한다. 

 

4. .gitignore 업데이트하기

.gitignore 파일을 업데이트하기 위해서 자신이 사용하는 편집기로 폴더를 연다. 
.gitignore 파일 맨 끝에 package-lock.json을 추가 후 저장해준다. (115줄 참고)

 

5. 해당 프로젝트 git init으로 초기화 및 저장소에 커밋

해당 프로젝트의 위치(./strapi 프로젝트명/)에서 아래의 git 명령어들을 실행해준다. 

# path: ./Strapi 프로젝트명/
git init
git add .
git commit -m "Initial Commit"

 

6. Heroku 프로젝트 생성하기

5번과 같은 경로에서 아래의 명령어를 실행해준다. 

# 자동생성되는 랜덤 프로젝트 명을 사용해도 괜찮은 경우
heroku create

# 자신이 프로젝트 명을 입력하고 싶을 때: <커스텀-프로젝트-명>.heroku.com으로 URL이 생성됨
heroku create <커스텀-프로젝트-명>

위의 명령어에 대한 결과로 Heroku 프로젝트 URL이 생성된다. 계속해서 데이터베이스 설정을 진행해보자.

 

7. Heroku 데이터베이스 설정

여기서는 PostgreSQL 기준으로 설정을 진행한다.

- Heroku Postgres addon 설치하기

Hobby Dev 플랜에서는 무료로 제공된다. 실제로 운영하기 위해 배포하는 경우 유료 플랜으로 바꾸는 것을 추천한다고 문서에 적혀있다. 
경로는 5번과 같은 ./Strapi 프로젝트명/ 이다. 아래와 같이 입력해준다. 

heroku addons:create heroku-postgresql:hobby-dev

성공적으로 설치가 되는 경우 "Database has been created and is available"이라는 문구와 함께 몇 마디가 더 출력된다. 

- 생성된 데이터베이스 확인하기

heroku config

위와 같이 입력하면, postgres://USERNAME:PASSWORD@HOST:PORT:DATABASE_NAME 과 같은 데이터베이스 URL이 출력된다. 
이 내용은 dashboard.heroku.com/apps 에서 본인이 생성한 Heroku 프로젝트를 선택 후 > Resources 탭 > Add-ons의 Heroku Postgres 클릭 

세 번째 탭 Settings > Database Credentials에서도 볼 수 있다. 

- 데이터베이스 변수 자동 설정하기

Strapi는 위에서 생성된 URL을 pg-connection-string 패키지를 사용해서 환경변수를 분석할 수 있다고 한다. Heroku에서 위의 URL을 변경하는 경우가 있기 때문에 변경된 URL에서 환경변수를 자동으로 분석하도록 pg-connection-string 패키지를 추가해준다. 

# npm 
npm install pg-connection-string --save

# yarn
yarn add pg-connection-string

- 운영환경 배포 위한 Heroku 데이터베이스 config 파일 생성하기

config 폴더 하위에 /env/production 폴더를 생성해주고 production 폴더 안에 database.js 를 생성해준다. 경로는 ./config/env/producton/database.js 이와 같아야 한다. 아래 그림 참고

database.js 파일에는 아래의 코드를 적는다. 

const parse = require('pg-connection-string').parse;
const config = parse(process.env.DATABASE_URL);

module.exports = ({ env }) => ({
  defaultConnection: 'default',
  connections: {
    default: {
      connector: 'bookshelf',
      settings: {
        client: 'postgres',
        host: config.host,
        port: config.port,
        database: config.database,
        username: config.user,
        password: config.password,
        ssl: {
          rejectUnauthorized: false,
        },
      },
      options: {
        ssl: true,
      },
    },
  },
});

새 데이터베이스 구성 파일이 사용되도록 Heroku의 NODE_ENV를 production으로 설정해준다. 경로는 Strapi 프로젝트가 위치한 곳이다.

heroku config:set NODE_ENV=production

- 운영환경을 위해서 Strapi server config 생성하기

database.js를 생성한 폴더에 server.js도 생성해준다. 

파일에 아래와 같이 코드를 입력한다. 

module.exports = ({ env }) => ({
  url: env('HEROKU_URL'),
});

 

터미널에서 Heroku에 환경변수를 설정해준다. 경로는 Strapi 프로젝트가 위치한 곳이다.

heroku config:set HEROKU_URL=$(heroku info -s | grep web_url | cut -d= -f2)

HEROKU_URL: https://<HEROKU-프로젝트-명>.herokuapp.com/ 같이 보인다. 

- (선택) 로컬 Strapi 프로젝트가 Postgres로 설정되어 있지 않다면 pg node modules 설치 필요

위에서 진행한 방법은 로컬 데이터베이스로 Postgres를 사용하기 때문에 필요하지 않음. 
만약 필요한 경우 아래와 같이 설치

npm install pg --save

 

8. 변경사항 커밋하기

터미널 혹은 IDE에서 아래와 같이 커밋한다. 경로는 Strapi 프로젝트가 위치한 곳이다.

git add .
git commit -m "Update database config" # 커밋 메시지는 알아서...

 

9. Yarn lockfile 업데이트

터미널에서 경로는 Strapi 프로젝트가 위치한 곳에서 아래와 같이 입력한다. 

yarn install

 

10. 변경사항 커밋하기

터미널 혹은 IDE에서 아래와 같이 커밋한다. 경로는 Strapi 프로젝트가 위치한 곳이다.

git add yarn.lock
git commit -m "Updated Yarn lockfile" # 커밋 메시지는 알아서...

 

11. 배포

터미널 혹은 IDE에서 아래와 같이 푸시한다. 경로는 Strapi 프로젝트가 위치한 곳이다.

git push heroku HEAD:main

배포는 몇 분 걸릴 수 있다. 배포가 끝나고 프로젝트 URL이 보이면 열어볼 수 있다. 터미널에 heroku open을 입력해도 된다. 
https://<HEROKU-프로젝트-명>.herokuapp.com/에서 Strapi 웰컴 페이지가 보인다면 성공이다! 🙌 

다음 편에서는 Github과 연결해서 자동 배포를 설정하는 법에 대해서 다뤄보겠다. 

 

📝 참조

https://strapi.io/documentation/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/heroku.html
https://tute.io/install-configure-strapi-postgresql