zellyy-finance/docs/02_기술_문서/Supabase_설정_가이드.md

Supabase 설정 가이드 - Debian 12 서버 설치

1. Supabase 소개

Supabase는 PostgreSQL 데이터베이스를 기반으로 하는 백엔드 서비스입니다. 다음과 같은 기능을 제공합니다:

• 데이터베이스: PostgreSQL 데이터베이스
• 인증: 사용자 인증 및 권한 관리
• 스토리지: 파일 저장 및 관리
• API: 자동 생성되는 RESTful API 및 실시간 구독
• Edge Functions: 서버리스 함수

이 가이드에서는 Debian 12 서버에 Supabase를 직접 설치하고 설정하는 방법을 안내합니다.

2. Debian 12 서버에 Supabase 설치

2.1 사전 요구 사항

1. Debian 12가 설치된 서버
2. 루트 또는 sudo 권한이 있는 사용자
3. 최소 사양:
   • CPU: 2코어 이상
   • RAM: 4GB 이상
   • 저장공간: 20GB 이상
   • 고정 IP 주소 (권장)

2.2 Docker 및 Docker Compose 설치

Supabase는 Docker 컨테이너로 실행되므로 먼저 Docker와 Docker Compose를 설치해야 합니다:

# 시스템 업데이트
sudo apt update
sudo apt upgrade -y

# 필요한 패키지 설치
sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release

# Docker 공식 GPG 키 추가
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Docker 저장소 추가
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Docker 설치
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io

# 현재 사용자를 docker 그룹에 추가 (sudo 없이 Docker 사용 가능)
sudo usermod -aG docker $USER

# Docker Compose 설치
sudo apt install -y docker-compose-plugin

설치 후 로그아웃했다가 다시 로그인하거나 다음 명령을 실행하여 그룹 변경사항을 적용합니다:

newgrp docker

2.3 Supabase 설치

1. Supabase 프로젝트 디렉토리 생성:

mkdir -p ~/supabase
cd ~/supabase

2. GitHub에서 Supabase Docker 프로젝트 클론:

git clone https://github.com/supabase/supabase.git
cd supabase/docker

3. 환경 변수 설정:

# .env 파일 편집
nano .env

다음 중요 변수들을 설정합니다. 예시는 적자 탈출 가계부 프로젝트의 실제 설정입니다 (실제 사용 시 보안키는 변경하세요):

# Supabase 설정
POSTGRES_PASSWORD=zellyy_finance_secure_password_2025
JWT_SECRET=$(openssl rand -base64 32)
ANON_KEY=$(openssl rand -base64 32)
SERVICE_ROLE_KEY=$(openssl rand -base64 32)

# API 및 사이트 URL
SITE_URL=https://your-domain.com
API_EXTERNAL_URL=https://your-domain.com
SUPABASE_PUBLIC_URL=https://your-domain.com
STUDIO_PORT=3000

# 대시보드 인증
DASHBOARD_USERNAME=your_username
DASHBOARD_PASSWORD=your_secure_dashboard_password

# PostgreSQL 설정
POSTGRES_HOST=db
POSTGRES_DB=postgres
POSTGRES_PORT=5432
POSTGRES_USER=postgres

# Kong 설정
KONG_HTTP_PORT=8000
KONG_HTTPS_PORT=8443

# 인증 설정
JWT_EXPIRY=3600
ENABLE_EMAIL_SIGNUP=true
ENABLE_EMAIL_AUTOCONFIRM=true
ENABLE_PHONE_SIGNUP=true
ENABLE_PHONE_AUTOCONFIRM=true
DISABLE_SIGNUP=false
ENABLE_ANONYMOUS_USERS=false
GOTRUE_EXTERNAL_ANONYMOUS_USERS_ENABLED=false

# 이메일 설정 (필요한 경우)
SMTP_ADMIN_EMAIL=admin@example.com
SMTP_HOST=mail.example.com
SMTP_PORT=587
SMTP_USER=smtp_user
SMTP_PASS=smtp_password
SMTP_SENDER_NAME=Zellyy Finance

# URL 경로 설정
MAILER_URLPATHS_CONFIRMATION=/auth/v1/verify
MAILER_URLPATHS_INVITE=/auth/v1/verify
MAILER_URLPATHS_RECOVERY=/auth/v1/verify
MAILER_URLPATHS_EMAIL_CHANGE=/auth/v1/verify

# 추가 설정
PGRST_DB_SCHEMAS=public,storage,graphql_public
SECRET_KEY_BASE=$(openssl rand -base64 32)
STUDIO_DEFAULT_ORGANIZATION=Default Organization
STUDIO_DEFAULT_PROJECT=Default Project
IMGPROXY_ENABLE_WEBP_DETECTION=true
FUNCTIONS_VERIFY_JWT=true
POOLER_TENANT_ID=tenant1
POOLER_DEFAULT_POOL_SIZE=20
POOLER_MAX_CLIENT_CONN=100
VAULT_ENC_KEY=$(openssl rand -base64 32)
POOLER_PROXY_PORT_TRANSACTION=6543

4. Supabase 시작:

docker compose up -d

이 명령은 모든 Supabase 서비스(PostgreSQL, Kong, GoTrue, PostgREST, Storage 등)를 백그라운드에서 시작합니다.

2.4 SSL/TLS 설정

프로덕션 환경에서는 HTTPS를 사용하는 것이 필수적입니다. Nginx와 Let's Encrypt를 사용하여 SSL을 설정하세요:

1. Nginx 및 Certbot 설치:

sudo apt install -y nginx certbot python3-certbot-nginx

2. Let's Encrypt를 통한 SSL 인증서 발급:

sudo certbot --nginx -d your-domain.com

3. Nginx 설정 파일 생성:

sudo nano /etc/nginx/sites-available/default

다음 내용을 추가합니다:

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    # Supabase Studio
    location / {
        proxy_pass http://localhost:3000;
    }

    # Supabase API (Kong)
    location /rest/v1/ {
        proxy_pass http://localhost:8000/rest/v1/;
    }

    # Supabase Auth
    location /auth/v1/ {
        proxy_pass http://localhost:8000/auth/v1/;
    }

    # Supabase Storage
    location /storage/v1/ {
        proxy_pass http://localhost:8000/storage/v1/;
    }

    # Supabase Realtime
    location /realtime/v1/ {
        proxy_pass http://localhost:8000/realtime/v1/;
    }
}

4. Nginx 설정 테스트 및 재시작:

sudo nginx -t
sudo systemctl restart nginx

※ 주의: Nginx 설정에서 proxy_set_header 지시문을 사용할 때 문법에 주의하세요. 필요한 경우 더 복잡한 헤더 설정을 사용할 수 있지만, 기본 설정으로도 충분히 작동합니다.

2.5 방화벽 설정

필요한 포트만 열도록 방화벽을 설정합니다:

sudo apt install -y ufw
sudo ufw allow ssh
sudo ufw allow http
sudo ufw allow https
sudo ufw enable

2.6 Supabase 관리

Supabase 서비스 관리를 위한 기본 명령어:

# 서비스 상태 확인
cd ~/supabase
docker compose ps

# 로그 확인
docker compose logs -f

# 서비스 중지
docker compose down

# 서비스 시작
docker compose up -d

# 서비스 재시작
docker compose restart

2.7 백업 설정

정기적인 데이터베이스 백업을 설정하는 것이 좋습니다:

1. 백업 스크립트 생성:

nano ~/backup-supabase.sh

다음 내용을 추가합니다:

#!/bin/bash
BACKUP_DIR=~/supabase-backups
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
mkdir -p $BACKUP_DIR

# PostgreSQL 백업
cd ~/supabase
docker compose exec db pg_dump -U postgres -d postgres > $BACKUP_DIR/supabase_$TIMESTAMP.sql

# 오래된 백업 삭제 (30일 이상)
find $BACKUP_DIR -name "supabase_*.sql" -type f -mtime +30 -delete

2. 스크립트에 실행 권한 부여:

chmod +x ~/backup-supabase.sh

3. Cron 작업 설정 (매일 백업):

crontab -e

다음 줄을 추가합니다:

0 2 * * * ~/backup-supabase.sh

2.8 모니터링 설정 (선택 사항)

서버 상태 모니터링을 위해 Prometheus와 Grafana를 설정할 수 있습니다:

# Prometheus와 Grafana 설치를 위한 Docker Compose 파일 다운로드
mkdir -p ~/monitoring
cd ~/monitoring
curl -L https://raw.githubusercontent.com/stefanprodan/dockprom/master/docker-compose.yml -o docker-compose.yml

# 서비스 시작
docker compose up -d

Grafana는 기본적으로 http://your-server-ip:3000에서 접근할 수 있으며, 기본 사용자 이름과 비밀번호는 admin/admin입니다.

3. 데이터베이스 설정

3.1 데이터베이스 접속

Supabase 설치 후 PostgreSQL 데이터베이스에 직접 접속할 수 있습니다:

cd ~/supabase
docker compose exec db psql -U postgres

3.2 테이블 생성 예시

다음과 같이 SQL 명령을 사용하여 테이블을 생성할 수 있습니다:

-- 사용자 테이블 생성
CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  email TEXT UNIQUE NOT NULL,
  password TEXT NOT NULL,
  full_name TEXT,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- RLS(Row Level Security) 정책 설정
ALTER TABLE users ENABLE ROW LEVEL SECURITY;
CREATE POLICY "사용자는 자신의 데이터만 볼 수 있음" ON users
  FOR SELECT USING (auth.uid() = id);
CREATE POLICY "사용자는 자신의 데이터만 수정할 수 있음" ON users
  FOR UPDATE USING (auth.uid() = id);

4. 인증 설정

4.1 이메일/비밀번호 인증 설정

자체 호스팅된 Supabase에서 이메일/비밀번호 인증을 설정하려면:

1. .env 파일에서 이메일 설정을 구성합니다:

   SMTP_HOST=your-smtp-host
   SMTP_PORT=587
   SMTP_USER=your-smtp-user
   SMTP_PASS=your-smtp-password
   SMTP_SENDER_NAME=Zellyy Finance
   

2. 변경 후 서비스를 재시작합니다:

   cd ~/supabase
   docker compose down
   docker compose up -d
   

4.2 소셜 로그인 설정 (선택 사항)

소셜 로그인을 추가하려면 각 제공업체의 설정을 .env 파일에 추가해야 합니다:

# Google OAuth
GOTRUE_EXTERNAL_GOOGLE_ENABLED=true
GOTRUE_EXTERNAL_GOOGLE_CLIENT_ID=your-google-client-id
GOTRUE_EXTERNAL_GOOGLE_SECRET=your-google-client-secret
GOTRUE_EXTERNAL_GOOGLE_REDIRECT_URI=https://your-domain.com/auth/v1/callback

# GitHub OAuth
GOTRUE_EXTERNAL_GITHUB_ENABLED=true
GOTRUE_EXTERNAL_GITHUB_CLIENT_ID=your-github-client-id
GOTRUE_EXTERNAL_GITHUB_SECRET=your-github-client-secret
GOTRUE_EXTERNAL_GITHUB_REDIRECT_URI=https://your-domain.com/auth/v1/callback

5. 스토리지 설정

영수증 이미지 등을 저장하기 위한 스토리지 버킷을 설정합니다:

5.1 스토리지 버킷 생성

SQL을 사용하여 스토리지 버킷을 생성할 수 있습니다:

-- PostgreSQL에 접속
cd ~/supabase
docker compose exec db psql -U postgres

-- 스토리지 버킷 생성
INSERT INTO storage.buckets (id, name, public)
VALUES ('receipts', 'receipts', false);

5.2 스토리지 보안 정책 설정

스토리지 버킷에 대한 접근 권한을 설정합니다:

-- 사용자는 자신의 파일만 업로드할 수 있음
CREATE POLICY "사용자는 자신의 파일만 업로드할 수 있음" ON storage.objects
  FOR INSERT WITH CHECK (auth.uid() = owner);

-- 사용자는 자신의 파일만 조회할 수 있음
CREATE POLICY "사용자는 자신의 파일만 조회할 수 있음" ON storage.objects
  FOR SELECT USING (auth.uid() = owner);

-- 사용자는 자신의 파일만 삭제할 수 있음
CREATE POLICY "사용자는 자신의 파일만 삭제할 수 있음" ON storage.objects
  FOR DELETE USING (auth.uid() = owner);

6. API 및 클라이언트 라이브러리

6.1 Supabase 클라이언트 설정 (Flutter)

Flutter 프로젝트에서 자체 호스팅된 Supabase를 사용하기 위한 설정:

1. 필요한 패키지 추가:

# pubspec.yaml
dependencies:
  supabase_flutter: ^1.10.14

2. 초기화 코드:

import 'package:supabase_flutter/supabase_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  await Supabase.initialize(
    url: 'https://your-domain.com',  // 자체 호스팅 서버 URL
    anonKey: 'your-anon-key',        // .env 파일에서 설정한 ANON_KEY
  );
  
  runApp(MyApp());
}

// 어디서나 클라이언트에 접근
final supabase = Supabase.instance.client;

6.2 기본 API 사용 예시

// 사용자 등록
Future<void> signUp(String email, String password) async {
  await supabase.auth.signUp(
    email: email,
    password: password,
  );
}

// 로그인
Future<void> signIn(String email, String password) async {
  await supabase.auth.signInWithPassword(
    email: email,
    password: password,
  );
}

// 데이터 조회
Future<List<Map<String, dynamic>>> getExpenses() async {
  final response = await supabase
    .from('expenses')
    .select()
    .eq('user_id', supabase.auth.currentUser!.id);
  
  return response;
}

// 데이터 추가
Future<void> addExpense(Map<String, dynamic> expenseData) async {
  await supabase
    .from('expenses')
    .insert(expenseData);
}

7. 유지 관리 및 모니터링

7.1 서비스 관리 명령어

Supabase 서비스 관리를 위한 기본 명령어:

# 서비스 상태 확인
cd ~/supabase
docker compose ps

# 로그 확인
docker compose logs -f

# 서비스 중지
docker compose down

# 서비스 시작
docker compose up -d

# 서비스 재시작
docker compose restart

# 특정 서비스만 재시작 (예: PostgreSQL)
docker compose restart db

7.2 데이터베이스 백업 및 복원

백업

cd ~/supabase
docker compose exec db pg_dump -U postgres -d postgres > backup_$(date +%Y%m%d).sql

복원

cd ~/supabase
cat backup_file.sql | docker compose exec -T db psql -U postgres -d postgres

7.3 업데이트

Supabase를 최신 버전으로 업데이트하려면:

cd ~/supabase
docker compose pull
docker compose down
docker compose up -d

8. 보안 모범 사례

1. API 키 보호: service_role 키는 절대 클라이언트 코드에 포함하지 마세요.
2. RLS(Row Level Security): 모든 테이블에 RLS 정책을 설정하세요.
3. 환경 변수: API 키와 같은 민감한 정보는 환경 변수로 관리하세요.
4. 정기적인 비밀번호 변경: 데이터베이스 비밀번호를 정기적으로 변경하세요.
5. 최소 권한 원칙: 각 사용자와 서비스에 필요한 최소한의 권한만 부여하세요.
6. 방화벽 설정: 필요한 포트만 개방하세요.
7. 정기적인 업데이트: 보안 패치를 위해 정기적으로 시스템을 업데이트하세요.

9. 문제 해결

9.1 문제 해결

1. 데이터베이스 연결 오류: .env 파일의 POSTGRES_PASSWORD 및 관련 데이터베이스 설정을 확인하세요.

2. SSL 인증서 오류: Certbot 설정 및 Nginx 구성을 확인하세요.

3. 스토리지 문제: .env 파일의 STORAGE_BACKEND 설정을 확인하세요.

4. 인증 오류: .env 파일의 JWT_SECRET, ANON_KEY, SERVICE_ROLE_KEY 설정을 확인하세요.

5. Pooler 서비스 재시작 문제:

   • 문제: supabase-pooler 서비스가 계속 재시작되는 문제
   • 해결: .env 파일에 SUPAVISOR_ENCRYPTION_KEY 변수를 추가하고 유효한 암호화 키를 설정
   • 추가 설정: POOLER_ENABLE_TENANT_SHARDING=true 옵션 추가로 성능 향상

6. Realtime 서비스 Unhealthy 상태:

   • 문제: realtime-dev.supabase-realtime 서비스가 Unhealthy 상태로 표시됨
   • 참고: 기본 CRUD 작업에는 영향을 주지 않으며, 실시간 기능을 사용하지 않는 경우 무시 가능
   • 디버깅: docker logs realtime-dev.supabase-realtime로 구체적인 오류 확인 가능

7. Nginx 리버스 프록시 502 오류:

   • 문제: Nginx에서 502 Bad Gateway 오류 발생
   • 해결:
     • Supabase Studio 컨테이너에 포트 매핑 추가 (3000:3000)
     • Nginx 설정에서 프록시 패스 설정 올바르게 구성
     • Docker 컨테이너와 Nginx 모두 재시작

8. 호스트 네임 설정 문제:

   • 문제: SITE_URL 설정이 올바르지 않아 인증 콜백 오류 발생
   • 해결: .env 파일에서 SITE_URL을 정확한 도메인으로 설정 (https://a11.ism.kr)

9.2 지원 받기

1. Supabase 문서
2. GitHub 이슈
3. Discord 커뮤니티

10. 다음 단계

Supabase 설치가 완료되면 다음 단계로 진행하세요:

1. 데이터베이스 스키마 구현
2. API 엔드포인트 개발
3. 인증 시스템 테스트
4. 프론트엔드 연동 준비

3. 데이터베이스 설정

3.3 Supabase Studio 접근

Supabase Studio는 데이터베이스 관리, API 탐색, 인증 설정 등을 위한 웹 기반 관리 인터페이스입니다.

https://your-domain.com

자체 호스팅 환경에서는 Supabase Studio에 별도의 로그인 없이 바로 접근할 수 있습니다. 이는 기본 설정이며, 추가적인 보안이 필요한 경우 Nginx 수준에서 기본 인증을 구성하는 것이 좋습니다.

참고: 클라우드 호스팅 Supabase와 달리, 자체 호스팅 환경에서는 Studio 접근에 대한 인증이 기본적으로 활성화되어 있지 않습니다. 프로덕션 환경에서는 추가 보안 조치를 고려하세요.

Nginx를 통한 기본 인증 추가 (선택 사항)

보안 강화를 위해 Nginx 설정에 기본 인증을 추가할 수 있습니다:

# htpasswd 파일 생성
sudo apt install apache2-utils
sudo htpasswd -c /etc/nginx/.htpasswd your-username

Nginx 설정 파일에 다음을 추가:

server {
    # 기존 설정...
    
    location / {
        # 기본 인증 추가
        auth_basic "Restricted Access";
        auth_basic_user_file /etc/nginx/.htpasswd;
        
        # 기존 프록시 설정...
        proxy_pass http://localhost:3000;
        # ...
    }
    
    # 다른 위치 블록...
}