G: 안녕하세요! 🚀 백엔드 개발을 빠르고 효율적으로 하고 싶은데, 기존 백엔드 구축은 너무 복잡하고 시간이 많이 든다고 느껴지시나요? 그렇다면 Supabase는 여러분의 게임 체인저가 될 수 있습니다. Firebase와 유사하지만 오픈 소스이고 PostgreSQL 기반이라 친숙하며, 실시간 데이터베이스, 인증, 스토리지, 함수 등 다양한 기능을 제공하죠.
대부분 Supabase를 클라우드 서비스(Supabase Cloud)로 이용하지만, 특정 이유(비용 절감, 데이터 주권, 커스터마이징, 보안 정책 등)로 직접 서버에 설치(Self-Hosting)를 원하는 분들이 많습니다. 하지만 직접 설치는 설정해야 할 것이 많고, 특히 API 도메인 설정에서 헤매는 경우가 잦습니다.
이 글에서는 Supabase를 여러분의 서버에 직접 설치하고, API 도메인 설정까지 한 번에 끝내는 방법을 상세하게 알려드릴게요! 💡
1. 왜 Supabase를 직접 설치해야 할까요? 🤔
클라우드 서비스가 편리한데 왜 직접 설치할까요? 다음과 같은 이유들이 있습니다.
- 비용 절감 💸: 특정 규모 이상으로 사용량이 많아지면 클라우드 비용이 부담될 수 있습니다. 자체 서버를 이용하면 장기적으로 비용을 절감할 수 있습니다.
- 완벽한 제어권 👑: 데이터베이스 설정, 서버 리소스 할당, 보안 정책 등 모든 것을 직접 제어할 수 있습니다.
- 데이터 주권 및 규제 준수 🔒: 민감한 데이터를 다루거나 특정 국가의 데이터 주권 규제를 준수해야 할 경우, 데이터를 직접 관리하는 것이 필수적일 수 있습니다.
- 커스터마이징 및 확장성 🔧: 필요한 경우 Supabase의 특정 컴포넌트를 커스터마이징하거나, 기존 인프라에 더 깊이 통합할 수 있습니다.
물론, 직접 설치는 서버 관리 및 유지보수, 보안 업데이트 등의 책임이 따르므로 충분한 이해가 필요합니다!
2. 시작 전 준비물 🎒
설치를 시작하기 전에 다음 준비물들이 필요합니다.
- 리눅스 서버 (Ubuntu 20.04+ 또는 CentOS 7+ 권장) 🐧: 최소 4GB RAM, 2vCPU 이상 권장합니다.
- Docker 및 Docker Compose 설치 🐳: Supabase의 모든 서비스는 Docker 컨테이너로 동작합니다.
- Docker 설치:
sudo apt update sudo apt install apt-transport-https ca-certificates curl software-properties-common -y curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt update sudo apt install docker-ce docker-ce-cli containerd.io -y sudo usermod -aG docker $USER # 현재 사용자에게 docker 권한 부여 (재로그인 필요) - Docker Compose 설치: (대부분 Docker와 함께 설치되지만, 최신 버전이 아닐 경우)
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose - 설치 확인:
docker --version,docker-compose --version
- Docker 설치:
- 도메인 이름 🌐: Supabase API에 접근할 도메인이 필요합니다 (예:
api.yourdomain.com). - DNS 관리 권한 📝: 도메인의 DNS 레코드를 설정할 수 있어야 합니다.
- SSH 접근 권한 🔑: 서버에 SSH로 접속할 수 있어야 합니다.
- 방화벽 설정 기본 지식 (선택 사항) 🔥: 필요한 포트 (80, 443)를 열어야 합니다.
3. Supabase Docker Compose 파일 준비 📦
Supabase는 모든 컴포넌트를 docker-compose.yml 파일 하나로 관리합니다. 공식 저장소에서 제공하는 파일을 기반으로 우리의 환경에 맞게 수정할 것입니다.
-
Supabase 리포지토리 클론:
git clone --depth 1 https://github.com/supabase/supabase cd supabase/docker이 디렉토리 안에
docker-compose.yml파일이 있습니다. -
.env파일 생성 및 환경 변수 설정: Supabase를 실행하기 위해 몇 가지 중요한 환경 변수가 필요합니다.docker-compose.yml파일과 같은 디렉토리에.env파일을 생성하고 다음 내용을 채워 넣으세요.# --- 필수 설정 --- POSTGRES_PASSWORD=your_strong_postgres_password # PostgreSQL 비밀번호 JWT_SECRET=a_very_long_and_random_secret_key_for_jwt_signing # JWT 서명용 시크릿 키 (아래 설명 참조) ANON_KEY=your_public_anon_key # 공개적으로 사용될 키 (아래 설명 참조) SERVICE_ROLE_KEY=your_service_role_key # 서비스 역할 키 (절대 외부에 노출 금지, 아래 설명 참조) # --- 도메인 설정 (가장 중요!) --- SUPABASE_PUBLIC_URL=https://api.yourdomain.com # Supabase API의 외부 접근 URL # --- 선택적 설정 --- # SMTP 서버 설정 (인증 이메일 발송용) SMTP_HOST=your_smtp_host SMTP_PORT=587 SMTP_USER=your_smtp_user SMTP_PASS=your_smtp_password SMTP_SENDER=no-reply@yourdomain.com # 스토리지 버킷 설정 (S3 호환 스토리지 사용 시) # AWS_S3_BUCKET=your-s3-bucket # AWS_ACCESS_KEY_ID=your-aws-access-key # AWS_SECRET_ACCESS_KEY=your-aws-secret-key # AWS_REGION=your-aws-region # Studio Dashboard가 사용할 URL (도메인 연결 시) # STUDIO_EXTERNAL_URL=https://studio.yourdomain.com # Studio를 별도 도메인으로 서비스할 경우POSTGRES_PASSWORD: 데이터베이스에 접속할 비밀번호입니다. 강력하게 설정하세요!JWT_SECRET: JWT(JSON Web Token) 서명에 사용되는 시크릿 키입니다. 최소 32자 이상의 무작위 문자열로 생성하는 것이 좋습니다. 다음 명령어로 생성할 수 있습니다.openssl rand -hex 32 # 예시: 91b7d5f0e9c8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2ANON_KEY,SERVICE_ROLE_KEY: 이 두 키는 Supabase 내부적으로 API 접근 권한을 관리하는 데 사용됩니다.docker-compose.yml파일이 실행될 때 자동으로 생성되지만,.env파일에 명시적으로 넣어주는 것이 좋습니다. 이 키들은 API에 접근할 때 사용되며,SERVICE_ROLE_KEY는 매우 강력한 권한을 가지므로 절대 외부에 노출되면 안 됩니다.- 임시로 생성하려면
head /dev/urandom | tr -dc A-Za-z0-9 | head -c 64 ; echo ''같은 명령어를 사용할 수 있습니다. 이후 Supabase Studio에서 실제 키를 확인할 수 있습니다.
- 임시로 생성하려면
SUPABASE_PUBLIC_URL: 이것이 핵심입니다! Supabase의 모든 API 엔드포인트가 외부에서 접근할 URL입니다. 이 URL을 기준으로 인증 이메일 링크, 스토리지 파일 URL 등이 생성됩니다. 반드시 HTTPS로 시작하고, 뒤에 슬래시(/)는 붙이지 마세요. (예:https://api.yourdomain.com)
-
docker-compose.yml파일 수정 (필요 시): 공식docker-compose.yml파일은 대부분의 경우 그대로 사용해도 됩니다. 하지만 특정 포트를 변경하거나, 볼륨 설정을 조절하는 등 환경에 맞게 수정해야 할 수도 있습니다. 특히, Kong 게이트웨이의 포트 매핑을 확인하세요. 기본적으로 8000(HTTP)과 8443(HTTPS)이 컨테이너 내부에 노출되어 있습니다.예를 들어, Kong 서비스가 호스트의 8000 포트로 매핑되어 있는지 확인합니다.
# supabase/docker/docker-compose.yml 파일 내용 중 일부 kong: # ... ports: - "8000:8000" # 외부 HTTP 접근 - "8443:8443" # 외부 HTTPS 접근 (나중에 Nginx/Caddy로 대체할 것임) # ...위와 같이
8000:8000이 설정되어 있다면, 호스트의 8000번 포트로 Kong에 접근할 수 있습니다. 우리는 이 포트를 Nginx/Caddy 같은 리버스 프록시를 통해 80/443 포트로 연결할 것입니다.
4. Supabase 실행 🚀
.env 파일과 docker-compose.yml 파일이 준비되었다면, 이제 Supabase를 실행할 차례입니다.
supabase/docker 디렉토리에서 다음 명령어를 실행합니다.
docker-compose up -d-d옵션은 백그라운드에서 컨테이너를 실행합니다.- 이 명령어를 실행하면 필요한 Docker 이미지를 다운로드하고 (시간이 좀 걸릴 수 있습니다), 모든 Supabase 서비스 컨테이너를 시작합니다.
컨테이너가 잘 실행되는지 확인하세요.
docker-compose ps모든 서비스(db, realtime, auth, storage, studio, kong 등)의 State가 Up으로 표시되면 성공입니다! 🎉
Name Command State Ports
-----------------------------------------------------------------------------------------------------------------------
supabase_auth_1 /usr/bin/gotrue Up 9999/tcp
supabase_db_1 docker-entrypoint.sh postgres Up 5432/tcp
supabase_functions_1 /usr/bin/functions Up 8081/tcp
supabase_kong_1 /docker-entrypoint.sh kong ... Up 0.0.0.0:8000->8000/tcp, 0.0.0.0:8443->8443/tcp
supabase_realtime_1 /usr/bin/realtime Up 4000/tcp
supabase_rest_1 /usr/bin/postgrest Up 8000/tcp
supabase_storage_1 /usr/bin/storage Up 5000/tcp
supabase_studio_1 /bin/sh -c yarn start Up 3000/tcp5. API 도메인 설정 (DNS 및 리버스 프록시) 🌐
이 부분이 많은 분들이 어려워하는 핵심입니다. SUPABASE_PUBLIC_URL로 설정한 도메인 (api.yourdomain.com)을 실제 Supabase API와 연결해 줄 차례입니다.
개념 이해:
- Supabase의 API 게이트웨이인 Kong은 서버 내부의
8000번 포트(HTTP) 또는8443번 포트(HTTPS)로 실행됩니다. - 우리는
api.yourdomain.com으로 들어오는 모든 웹 요청을 이 Kong 게이트웨이로 전달해야 합니다. - 이를 위해 리버스 프록시(Reverse Proxy)를 사용합니다. 가장 대중적인 리버스 프록시는 Nginx 또는 Caddy입니다. 이 글에서는 Nginx를 기준으로 설명하겠습니다.
- 또한, HTTPS 보안을 위해 SSL/TLS 인증서 (Let’s Encrypt 추천)를 설정해야 합니다.
-
DNS 레코드 설정: 도메인 관리 서비스(가비아, 호스팅케이알, Cloudflare 등)에 접속하여
api.yourdomain.com도메인이 여러분 서버의 IP 주소를 가리키도록 A 레코드를 추가합니다.- 타입:
A - 이름/호스트:
api(또는@또는yourdomain.com등, 서비스에 따라 다름) - 값/IP 주소: 여러분 서버의 공인 IP 주소
변경 사항이 적용되는 데 몇 분에서 몇 시간까지 걸릴 수 있습니다 (DNS 전파 시간).
- 타입:
-
Nginx 설치 및 설정:
- Nginx 설치:
sudo apt update sudo apt install nginx -y sudo systemctl start nginx sudo systemctl enable nginx -
Nginx 설정 파일 생성:
/etc/nginx/sites-available/디렉토리에supabase.conf파일을 생성합니다.sudo nano /etc/nginx/sites-available/supabase.conf파일에 다음 내용을 붙여넣고 저장합니다. (주의:
yourdomain.com을 실제 도메인으로 변경하세요!)server { listen 80; listen [::]:80; server_name api.yourdomain.com; # 여러분의 API 도메인 # Let's Encrypt를 위한 설정 (추후 SSL 발급 시 필요) location /.well-known/acme-challenge/ { root /var/www/certbot; } location / { return 301 https://$host$request_uri; # HTTP 요청을 HTTPS로 리디렉션 } } server { listen 443 ssl http2; listen [::]:443 ssl http2; server_name api.yourdomain.com; # 여러분의 API 도메인 # SSL 인증서 경로 (Let's Encrypt로 발급 후 여기에 설정) ssl_certificate /etc/letsencrypt/live/api.yourdomain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/api.yourdomain.com/privkey.pem; # SSL 설정 (보안 강화) ssl_session_cache shared:SSL:10m; ssl_session_timeout 10m; ssl_protocols TLSv1.2 TLSv1.3; ssl_prefer_server_ciphers on; ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384'; ssl_stapling on; ssl_stapling_verify on; resolver 8.8.8.8 8.8.4.4 valid=300s; resolver_timeout 5s; add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; # Supabase Kong 게이트웨이로 요청 프록시 location / { proxy_pass http://localhost:8000; # Kong 컨테이너의 8000번 포트 (호스트에 매핑된 포트) proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_redirect off; proxy_buffering off; # 실시간 기능을 위해 버퍼링 끄기 proxy_http_version 1.1; # 웹소켓을 위해 필요 proxy_set_header Upgrade $http_upgrade; # 웹소켓을 위해 필요 proxy_set_header Connection "upgrade"; # 웹소켓을 위해 필요 } } - 설정 파일 활성화:
sudo ln -s /etc/nginx/sites-available/supabase.conf /etc/nginx/sites-enabled/ sudo nginx -t # Nginx 설정 파일 문법 검사 sudo systemctl restart nginx # Nginx 재시작
- Nginx 설치:
-
Let’s Encrypt SSL 인증서 발급 (Certbot): HTTPS를 위해 무료 SSL 인증서인 Let’s Encrypt를 사용합니다. Certbot 도구를 이용하면 쉽게 발급 및 갱신할 수 있습니다.
-
Certbot 설치:
sudo snap install core sudo snap refresh core sudo snap install --classic certbot sudo ln -s /snap/bin/certbot /usr/bin/certbot -
Nginx용 인증서 발급:
sudo certbot --nginx -d api.yourdomain.com # 여러분의 API 도메인으로 변경프롬프트에 따라 이메일 주소를 입력하고 약관에 동의하면 자동으로 인증서를 발급받고 Nginx 설정을 업데이트해 줄 것입니다. (기존 80번 포트 리다이렉션 설정이 있다면
certbot이 자동으로 처리해줍니다.) -
자동 갱신 테스트:
sudo certbot renew --dry-run이 명령어가 성공하면 자동으로 갱신 설정도 완료된 것입니다.
-
-
방화벽 설정 (선택 사항): 서버 방화벽이 활성화되어 있다면, 80번(HTTP)과 443번(HTTPS) 포트를 열어줘야 합니다. UFW(Uncomplicated Firewall)를 사용한다면:
sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable # 방화벽 활성화 (이미 되어있다면 Skip)
6. 설치 확인 및 테스트 ✅
이제 모든 설정이 완료되었습니다. api.yourdomain.com으로 접속하여 Supabase API가 잘 작동하는지 확인해 봅시다!
-
Supabase Studio 접속: 웹 브라우저에서
https://api.yourdomain.com으로 접속해보세요. 정상적으로 연결되었다면 Supabase Studio 로그인 화면이 나타날 것입니다.- 이메일:
supabase(기본값) - 비밀번호:
.env파일에 설정한POSTGRES_PASSWORD
로그인 후 대시보드에서 프로젝트를 관리하고 테이블을 만들 수 있습니다.
- 이메일:
-
API 테스트:
curl명령어를 사용하여 API 호출을 테스트해볼 수 있습니다.-
인증 정보 확인 (
.env파일의 ANON_KEY와 SERVICE_ROLE_KEY 사용): Supabase Studio에 로그인한 후, 왼쪽 사이드바에서Project Settings->API로 이동하면Project API keys섹션에서anon public과service_role키를 확인할 수 있습니다. 이 키들을.env파일에 복사해 넣어주세요. -
테이블 생성 및 데이터 삽입 (예시): Supabase Studio에서 새로운 테이블을 생성합니다. 예를 들어
countries라는 테이블을 만들고name이라는text컬럼을 추가한 뒤 몇 개의 데이터를 삽입합니다. -
REST API 호출:
curl -X GET \ -H "apikey: YOUR_ANON_KEY_HERE" \ -H "Authorization: Bearer YOUR_ANON_KEY_HERE" \ "https://api.yourdomain.com/rest/v1/countries" # 여러분의 API 도메인 및 테이블명YOUR_ANON_KEY_HERE를.env파일의ANON_KEY값으로 변경하세요.countries테이블의 데이터가 JSON 형식으로 반환되면 성공입니다! -
인증 API 호출 (예시: 회원가입):
curl -X POST \ -H "apikey: YOUR_ANON_KEY_HERE" \ -H "Content-Type: application/json" \ -d '{ "email": "test@example.com", "password": "password123" }' \ "https://api.yourdomain.com/auth/v1/signup"성공 시 사용자 정보가 반환됩니다. (SMTP 설정이 되어있다면 확인 이메일이 발송됩니다.)
-
7. 추가 고려 사항 및 유지보수 ⚠️
직접 설치한 Supabase를 안정적으로 운영하기 위해 다음 사항들을 고려하세요.
- 백업 및 복구 💾: PostgreSQL 데이터베이스 백업은 필수입니다. 주기적으로
pg_dump를 사용하여 데이터를 백업하고 안전한 곳에 보관해야 합니다.docker-compose exec db pg_dump -U postgres -d postgres > supabase_db_backup_$(date +%F).sql - 업데이트 🔄: Supabase 컴포넌트들은 지속적으로 업데이트됩니다. 보안 패치 및 새로운 기능을 위해 주기적으로 업데이트를 확인하고 적용하세요.
cd supabase/docker # docker-compose.yml이 있는 디렉토리 git pull # 최신 Supabase 리포지토리 코드 가져오기 docker-compose pull # 최신 Docker 이미지 다운로드 docker-compose up -d # 업데이트된 컨테이너 실행주의: 메이저 업데이트 시에는 변경 사항이 있을 수 있으니 공식 문서를 꼭 확인하세요.
- 보안 강화 🔒:
- 강력한
POSTGRES_PASSWORD,JWT_SECRET, API 키 사용. - 서버 방화벽 설정 (필요한 포트만 열기).
- SSH 접근 보안 강화 (키 기반 인증, 비밀번호 비활성화).
- 정기적인 시스템 및 소프트웨어 업데이트.
- 강력한
- 모니터링 및 로깅 📊: 서버 리소스(CPU, RAM, 디스크) 사용량과 Supabase 컨테이너 로그를 주기적으로 모니터링하여 문제 발생 시 신속하게 대응하세요.
- 확장성 📈: 서비스 규모가 커지면 단일 서버로는 한계가 있습니다. 이때는 Docker Swarm, Kubernetes와 같은 컨테이너 오케스트레이션 도구를 활용하여 확장성을 확보하는 것을 고려해야 합니다.
결론 🎉
이 가이드를 통해 여러분은 Supabase를 직접 서버에 설치하고, API 도메인 설정까지 완벽하게 마치는 방법을 배웠습니다. 이제 여러분만의 강력하고 유연한 백엔드 인프라를 구축할 수 있게 된 것입니다!
물론 직접 관리는 책임이 따르지만, 얻는 이점 또한 많습니다. 개발의 자유를 만끽하며 멋진 애플리케이션을 만들어 나가시길 응원합니다! 궁금한 점이 있다면 언제든지 댓글로 문의해주세요. 해피 코딩! 🥳