이용 가이드
Getting Started
PlusX Developers
리소스 발급부터 사내 서비스 공개까지
프로젝트의 기본 기능 구현 이후, 운영 환경 구축에 필요한 리소스를 제공하는 사내 플랫폼입니다. 인스턴스, RDB, SSO를 신청하고 관리하며, 운영 준비가 완료된 프로젝트를 Station에 공개할 수 있습니다.
내 프로젝트에 필요한 리소스
아래 질문을 따라 실행 환경, 데이터 저장, 사내 로그인을 차례로 확인하세요. 사용자 기기에서 실행하는 프로젝트도 필요한 기능에 따라 DB나 SSO를 사용할 수 있습니다.
내 컴퓨터를 꺼도 서비스나 자동 작업이 계속 실행되어야 하나요?
사용자의 컴퓨터에서 실행
설치형 앱이나 확장 프로그램처럼
각자 설치해 사용하는 방식입니다.
인스턴스 발급
내 컴퓨터 대신 서비스를 실행할
컴퓨터를 발급받습니다.
여러 사용자가 같은 데이터를 저장하고 조회해야 하나요?
별도 RDB 없이 진행
저장이 필요 없거나,
각자 기기에만 저장하는 경우입니다.
서비스와 DB를 분리해 운영해야 하나요?
데이터가 많거나 조회가 잦다면
코딩 에이전트와 분리 여부를 확인하세요.
인스턴스에 DB 함께 설치
인스턴스 자원을 나눠 사용하며
인스턴스를 중지하면 DB도 중지됩니다.
같은 환경의 인스턴스가 필요합니다.
별도 RDB 발급
서비스와 DB를 분리해 운영합니다.
별도 비용이 발생하며,
같은 환경의 인스턴스 발급 후 신청합니다.
사내 계정으로 로그인하는 기능이 필요한가요?
내 컴퓨터에서 로그인 기능을 테스트하는 단계인가요?
SSO 없이 진행
다른 로그인이나 접근 제한이 필요하면
프로젝트에서 별도로 구현합니다.
Dev SSO
인스턴스 없이 내 컴퓨터에서
사내 로그인을 테스트합니다.
Staging / Production SSO
같은 환경의 인스턴스가 필요합니다.
HTTPS는 직접 설정해야 합니다.
Station 릴리즈 신청
1차와 2차 결재 승인 후 공개
필요할 때 찾아보세요
Starter Kit
Starter Kit
프로젝트의 작업 기준을 잡는
바이브코딩 스타터 키트
새 프로젝트의 개발을 시작할 때, 코딩 에이전트와 공유할 작업 규칙과 기록을 준비하는 문서 묶음입니다.
Developers는 기본 기능이 구현된 프로젝트를 대상으로, 운영 리소스 확보와 Station 공개를 준비하는 단계에서 이용합니다.
Station과 Developers 업데이트 예정
현재 버전에는 두 플랫폼의 역할과 이용 절차가 포함되어 있지 않습니다.
키트만 적용하면 코딩 에이전트가 이 내용을 알지 못할 수 있으므로, 업데이트 전에는 이용 가이드의 관련 설명과 연동 정보를 별도로 전달해 주십시오.
Starter Kit이란
기본 작업 지침과 기록 양식에 프로젝트의 기준을 채워 두면, 세션이 변경되어도 같은 맥락에서 작업을 이어갈 수 있습니다. 프로젝트의 기능이나 화면을 대신 만드는 코드 템플릿은 아니며, 디자인 시스템의 상세 문서, 토큰, 컴포넌트와 서비스 구조도는 직접 추가해야 합니다.
사용 전 확인
프로젝트 상태에 따라 적용 방법과 확인해야 할 항목이 달라집니다.
| 확인 항목 | 적용 기준 |
|---|---|
| 새 프로젝트 | 압축을 해제한 파일을 프로젝트 최상위 폴더에 넣고 디자인 시스템을 선택합니다. |
| 기존 프로젝트 | 같은 이름의 파일을 바로 덮어쓰지 않고 기존 규칙과 Starter Kit의 내용을 먼저 비교하여 통합합니다. |
| 디자인 시스템 | 프로젝트 기준에 따라 PlusX 또는 Carbon을 선택하고, 사용할 기준 문서와 토큰 파일을 design-kit/에 추가합니다. 이미 확정된 디자인 시스템이 있다면 기존 기준을 우선합니다. |
| 민감 정보 | 비밀번호, API 키 및 인증 파일은 지침이나 작업 기록에 입력하지 않습니다. |
Starter Kit은 신규 프로젝트에 적용하는 것을 권장합니다.
기존 프로젝트에 적용할 때는 현재 규칙과 기록이 삭제되지 않도록 파일별 내용을 확인하십시오.
구성 파일
각 파일은 코딩 에이전트의 작업 기준과 세션 간 기록을 구분하여 관리합니다.
- AGENT.md
작업 규칙 · 에이전트의 역할·작업 범위·실행 기준
- AGENT_STATE.md
현재 상태 · 진행 상황·결정 사항·다음 작업
- WORKLOG.md
작업 기록 · 완료한 작업과 주요 변경 이력
- design-kit/
디자인 기준 · README 안내에 따라 실제 문서·토큰을 직접 추가
- guides/
참고 자료 · 기본 팁과 README 포함, 구조도·상세 가이드는 직접 추가
- README.md
시작 안내 · 키트의 구성과 기본 적용 방법
적용 절차
다운로드한 파일을 프로젝트에 적용한 후 코딩 에이전트가 지침을 읽도록 요청합니다.
ZIP 파일의 압축을 해제하고 프로젝트 최상위 폴더에 파일을 넣습니다.
AGENT.md에서 디자인 시스템을 선택하고 해당 기준 자료를 추가합니다.
코딩 에이전트에 “AGENT.md를 읽고 실행해줘.”라고 요청합니다.
세션 종료 전 #end를 입력하여 현재 상태와 작업 내용을 기록합니다.
작업 중 활용
문서의 역할을 구분하여 필요한 시점에 최신 상태로 유지합니다.
| 상황 | 진행 방법 |
|---|---|
| 새 규칙을 결정한 경우 | 코딩 에이전트가 다음 작업부터 동일한 기준을 적용할 수 있도록 AGENT.md에 반영합니다. |
| 현재 상태를 인계해야 하는 경우 | 완료 항목, 진행 중인 항목 및 다음 작업을 AGENT_STATE.md에 정리합니다. |
| 작업을 종료하는 경우 | #end를 입력하여 주요 변경 내용을 WORKLOG.md에 기록합니다. |
| 새 세션을 시작하는 경우 | 코딩 에이전트가 지침과 현재 상태를 먼저 확인하도록 요청한 후 작업을 시작합니다. |
프로젝트 시작
프로젝트란
코드 자체를 저장하는 공간은 아닙니다. 프로젝트 이름과 설명을 기준으로 필요한 자원과 신청 내역을 연결하여 관리합니다.
생성 전 확인
프로젝트의 목적과 관리 범위를 명확하게 전달할 수 있는 정보를 준비합니다.
| 준비 항목 | 작성 기준 |
|---|---|
| 프로젝트 이름 | 다른 구성원이 목적을 쉽게 식별할 수 있는 이름을 입력합니다. |
| 한 줄 설명 | 해결하려는 문제와 주요 사용자를 간결하게 작성합니다. |
| 관리 단위 | 하나의 배포 대상에는 하나의 프로젝트 생성을 권장합니다. Dev, Staging 및 Production은 프로젝트 내부에서 구분합니다. |
프로젝트 생성
프로젝트는 별도 전자 결재 없이 즉시 생성됩니다.
내 프로젝트에서 새 프로젝트를 선택합니다.
프로젝트 이름과 한 줄 설명을 입력합니다.
프로젝트 생성을 선택하고 상세 화면으로 이동합니다.
생성 후 진행
프로젝트 형태와 필요한 기능에 따라 다음 작업을 선택합니다.
| 필요한 기능 | 다음 작업 |
|---|---|
| 지속적인 웹 실행 | 인스턴스를 신청합니다. |
| 구조화된 정보 저장 | 내장 PostgreSQL 또는 별도 DB를 선택합니다. 별도 DB는 같은 프로젝트·같은 환경의 인스턴스를 먼저 발급한 뒤 신청합니다. |
| 사내 계정 로그인 | Staging·Production SSO는 같은 프로젝트·같은 환경의 인스턴스를 먼저 발급한 뒤 신청합니다. Dev SSO만 인스턴스 없이 신청할 수 있습니다. |
| 별도 자원이 필요 없는 설치형 프로그램 | 자원 발급 없이 Station 릴리즈를 신청합니다. |
자원 발급은 선택 사항입니다.
프로젝트에 필요한 자원만 신청하거나, 별도 자원이 필요하지 않은 경우 바로 Station 릴리즈를 진행할 수 있습니다.
인스턴스 발급
인스턴스란
바이브코딩 중에는 내 컴퓨터에서 프로젝트를 실행하지만, 다른 사용자가 언제든 접속하려면 계속 가동되는 실행 공간이 필요합니다. 인스턴스는 서버 기능과 자동 작업을 실행하고 외부 접속에 필요한 도메인과 IP를 제공합니다.
배포란
코드가 완성되더라도 내 컴퓨터에서만 실행하면 다른 사용자는 이용할 수 없습니다. 프로젝트 형태에 따라 실행 공간, 정보 저장 또는 로그인 기능 중 필요한 요소만 준비합니다. 설치형 프로그램처럼 별도 자원이 필요하지 않은 프로젝트는 Station 릴리즈만 진행할 수 있습니다.
코딩 에이전트에게 전달하기
배포할 환경을 골라 전달하세요. 발급 후 접속 정보는 연동 가이드에 따라 직접 입력하며, PEM 파일 내용은 공유하지 마세요.
코드를 확인하고 이 프로젝트를 PlusX Developers의 [Staging / Production] 인스턴스에 배포할 준비를 도와줘. 기본 도메인 연결은 인스턴스 발급·활성화 과정에서 자동으로 설정돼. Certbot으로 SSL/TLS 인증서를 발급·적용하고 HTTPS를 설정해줘. 인증서 자동 갱신도 설정해줘. 접속 정보는 내가 .env에 직접 입력할 테니 파일은 수정하지 말아줘.
선택 기준
프로젝트가 작동하는 방식에 따라 인스턴스가 필요한지 먼저 확인합니다.
| 프로젝트의 상황 | 권장 방식 |
|---|---|
| 로그인, 정보 저장, 파일 처리 또는 자동 작업이 필요한 경우 | 인스턴스를 신청하여 서버 기능을 계속 실행합니다. |
| 설치형 프로그램처럼 별도 실행 공간이 필요하지 않은 경우 | 인스턴스를 신청하지 않고 Station 릴리즈를 진행할 수 있습니다. |
인스턴스는 선택 자원입니다.
설치형 프로그램처럼 별도 실행 공간이 필요하지 않은 프로젝트는 발급하지 않아도 됩니다.
발급 전 확인
신청 화면에서 입력하거나 선택해야 하는 항목을 사전에 준비합니다.
| 준비 항목 | 안내 |
|---|---|
| 환경 | 기능 검증은 Staging, 실제 사용자에게 제공하는 운영 환경은 Production을 선택합니다. |
| 슬러그 | 도메인에서 프로젝트를 구분하는 이름입니다. 영문 소문자, 숫자, 하이픈(-)으로 입력합니다. 예를 들어 team-book을 입력하면 아래 주소가 발급됩니다. Production: team-book.plusxdev.com Staging: stage.team-book.plusxdev.com |
| 슬러그 변경 | 한 프로젝트의 모든 환경은 같은 슬러그를 사용합니다. 변경하려면 해당 프로젝트의 Staging·Production 인스턴스를 모두 삭제하고, 삭제가 완료된 후 새 슬러그로 다시 발급해야 합니다. 중지만으로는 변경할 수 없습니다. 각 환경에 별도 DB가 남아 있다면 DB 삭제를 먼저 완료해야 인스턴스를 삭제할 수 있습니다. 삭제 전 필요한 데이터와 설정을 백업하십시오. 진행 중인 발급 신청이 있으면 기존 슬러그가 유지되므로 담당자에게 먼저 확인합니다. |
| 실행 정보 | 프로젝트 실행 방법과 필요한 환경 변수를 코딩 에이전트와 정리합니다. |
| PostgreSQL 함께 설치 | 프로젝트를 실행하는 인스턴스 안에 DB를 함께 설치하는 옵션입니다. 소규모 내부 도구나 기능 검증용 프로젝트에서 우선 검토할 수 있습니다. 앱과 DB가 처리 능력·메모리·저장 공간을 나눠 쓰며, 인스턴스를 중지하면 DB도 함께 중지됩니다. 사용량이 많거나 앱과 DB를 분리해 운영해야 한다면 별도 DB 발급을 검토합니다. |
발급 및 활성화
전자 결재 승인과 발급 활성화는 서로 다른 단계입니다.
프로젝트 상세의 발급 리소스에서 인스턴스로 이동합니다.
환경, 슬러그 및 PostgreSQL 설치 여부를 확인하고 제출합니다.
승인이 완료될 때까지 전자 결재에서 진행 상태를 확인합니다.
발급 활성화를 선택하고 준비가 완료되면 활성 상태를 확인합니다.
별도 DB와 Staging·Production SSO는 인스턴스 발급이 먼저입니다.
같은 프로젝트·같은 환경의 인스턴스가 먼저 발급되어 있어야 신청할 수 있습니다. Dev SSO만 인스턴스 없이 신청할 수 있습니다.
도메인 연결과 HTTPS 설정
웹 프로젝트를 공개하려면 접속할 주소를 연결하고 안전하게 통신할 수 있도록 설정해야 합니다. 기본 도메인 연결은 Developers가 자동으로 처리하며, SSL/TLS 인증서 발급·적용과 HTTPS 설정은 Certbot으로 직접 진행합니다.
도메인 연결 · DNS
team-book.plusxdev.com
접속할 컴퓨터의 위치
- 원래 필요한 작업
- 사용자가 도메인을 입력하면 인스턴스를 찾도록, DNS에 도메인과 IP를 연결하는 레코드를 등록합니다.
- Developers가 자동으로
- 신청한 슬러그·환경에 맞는 기본 도메인을 준비하고 발급된 인스턴스 IP에 연결합니다.
안전한 통신 · HTTPS
로그인 정보·입력 데이터
암호화된 통신으로 접속
- 원래 필요한 작업
- 도메인 소유권을 확인해 SSL/TLS 인증서를 발급받고 웹 서버에 적용합니다. 전송 중인 데이터를 암호화하는 작업입니다.
- 직접 설정할 작업
- 코딩 에이전트와 함께 프로젝트의 웹 서버 구성에 맞춰 Certbot으로 SSL/TLS 인증서를 발급·적용하고 HTTPS를 설정합니다.
- 자동 갱신이 필요한 이유
- 인증서는 유효기간이 있어 만료 전에 갱신해야 합니다. 자동 갱신은 서버가 정기적으로 갱신 필요 여부를 확인하고 필요한 인증서를 새로 발급받도록 설정하는 작업입니다.
- 설정 후 확인
- 코딩 에이전트와 갱신 작업의 자동 실행 설정과 갱신 테스트 통과 여부를 확인합니다. 갱신된 인증서를 웹 서버가 다시 읽어 적용하는 과정도 함께 점검합니다.
기본 도메인 연결은 자동으로 준비되며, HTTPS는 직접 설정해야 합니다.
프로젝트 코드 배포, 환경 변수 입력, 서비스 실행과 필요한 DB·SSO 연결도 별도로 진행해야 합니다.
활성화 후 확인
발급 카드에서 프로젝트 배포에 필요한 정보를 확인합니다.
| 확인 항목 | 의미 |
|---|---|
| 상태 | 활성으로 표시되면 인스턴스 준비가 완료된 상태입니다. |
| 도메인 | 다른 사용자가 웹 프로젝트에 접속할 때 사용하는 주소입니다. |
| IP | 인스턴스를 식별하고 연결할 때 사용하는 네트워크 주소입니다. |
| PEM 키 | 인스턴스에 안전하게 접속할 때 사용하는 전자 열쇠 파일입니다. |
PEM 키는 활성화 시 한 번만 다운로드할 수 있습니다.
다운로드 폴더에 저장된 파일은 프로젝트 상세의 인스턴스 탭 → 연동 가이드 → ‘PEM Key 보관하기’ 안내에 따라
개인 홈 폴더의 ~/.ssh/로 옮기고, 본인만 읽을 수 있도록 파일 권한을 설정하십시오.
Git 저장소, 메신저 또는 이메일에 업로드하지 마십시오. 분실한 파일은 다시 다운로드할 수 없습니다.
프로젝트 배포로 이어가기
인스턴스 활성화는 실행 공간의 준비 완료를 뜻합니다. 프로젝트 코드가 자동으로 배포되는 것은 아닙니다.
프로젝트 상세의 인스턴스 탭에서 연동 가이드와 배포할 환경의 접속 정보를 확인합니다.
프로젝트 실행 방법과 환경 변수, 필요한 DB·SSO 연결을 점검하고 배포합니다. Certbot으로 인증서를 발급·적용해 HTTPS도 설정합니다.
발급된 도메인에서 화면이 열리는지 확인하고 로그인·저장 등 주요 기능을 검증합니다.
접속 정보는 배포할 환경과 일치해야 합니다.
Staging과 Production을 혼동하지 않도록 확인하고, PEM 키와 비밀번호 같은 비밀값은 대화나 작업 기록에 붙여 넣지 마십시오.
인스턴스 삭제 전 확인
같은 프로젝트·같은 환경의 별도 DB가 있다면 DB 삭제를 먼저 완료해야 인스턴스 삭제를 신청할 수 있습니다. DB 삭제 신청이나 승인만 받은 상태, 삭제 중인 상태에서는 아직 인스턴스를 삭제할 수 없습니다.
내장 PostgreSQL과 별도 DB는 삭제 방식이 다릅니다.
‘PostgreSQL 함께 설치’로 생성한 내장 DB는 별도 DB 삭제 대상이 아니라 인스턴스와 함께 삭제되는 데이터입니다.
인스턴스 삭제 전 필요한 데이터를 별도로 백업하고 복구 가능 여부를 확인하십시오.
DB 발급
DB란
회원 이름, 게시글 제목, 예약 날짜처럼 항목이 정해진 정보를 표와 유사한 구조로 정리하여 보관합니다.
PostgreSQL이란
회원 정보, 게시글, 예약 내역 등을 보관하고, 프로젝트에서 필요한 데이터를 조회·추가·수정·삭제할 수 있도록 합니다.
Developers에서는 인스턴스 내장 DB와 별도 DB 모두 PostgreSQL을 사용합니다. 두 방식은 DB의 종류가 아니라 설치 위치와 사용하는 자원이 다릅니다.
코딩 에이전트에게 전달하기
먼저 필요한 DB 방식을 확인하세요. 발급 후 접속 정보는 직접 입력하며, 비밀번호는 대화에 공유하지 마세요.
이 프로젝트에 PlusX Developers의 PostgreSQL을 연결하려고 해. 코드를 보고 내장 DB와 별도 DB 중 필요한 방식과 연결 위치를 확인해줘. 기존 데이터는 유지해줘. 접속 정보는 내가 .env에 직접 입력할 테니 파일은 수정하지 말아줘.
선택 기준
먼저 정보를 저장할 DB가 필요한지 판단한 뒤, 필요하다면 내장 PostgreSQL과 별도 DB 중에서 선택합니다. 저장 기능이 있다는 이유만으로 별도 DB를 발급할 필요는 없습니다.
| 프로젝트의 상황 | 권장 방식 |
|---|---|
| 소개 페이지·단순 계산기처럼 정보를 저장하지 않는 경우 | DB를 발급하거나 PostgreSQL을 함께 설치하지 않아도 됩니다. |
| 소수 구성원이 쓰는 예약 목록·간단한 설문·업무 도구 또는 기능 검증용 프로젝트 | 내장 PostgreSQL을 우선 검토할 수 있습니다. 앱과 DB를 한 인스턴스에서 운영하므로 별도 DB 발급을 줄일 수 있지만, 인스턴스에 두 기능을 실행할 여유가 있는지 확인합니다. |
| 동시에 사용하는 사람이 많거나 검색·집계가 잦고 저장량이 계속 늘어나는 경우 | 별도 DB를 검토합니다. 앱과 DB의 자원을 분리해 서로의 부하가 한 인스턴스에 집중되지 않도록 할 수 있습니다. 실제 사용량에 맞는 용량과 비용은 담당자와 확인합니다. |
| 앱과 DB의 실행 자원·운영 상태를 따로 관리해야 하는 경우 | 별도 DB를 검토합니다. 단, 앱 인스턴스가 중지되면 DB가 남아 있어도 서비스는 이용할 수 없습니다. Developers에서는 같은 환경의 별도 DB가 남아 있는 동안 인스턴스를 삭제할 수 없으므로, 교체가 필요하면 데이터 백업·이전 계획을 먼저 확인합니다. |
| 중요한 운영 데이터를 장기간 보관해야 하는 경우 | 프로젝트 규모와 관계없이 백업 주기, 보관 위치 및 복구 방법을 먼저 정합니다. 내장·별도 DB 중 어떤 방식이 이 운영 기준을 충족하는지 코딩 에이전트와 담당자에게 확인합니다. |
별도 DB는 인스턴스 발급 후 신청할 수 있는 선택 자원입니다.
같은 프로젝트·같은 환경의 인스턴스가 먼저 발급되어 있어야 합니다. 예를 들어 Production DB를 신청하려면 Production 인스턴스가 필요하며, Staging 인스턴스만으로는 신청할 수 없습니다. Dev 환경에는 별도 DB를 발급하지 않습니다.
내장 PostgreSQL과 별도 DB의 차이
두 방식 모두 정보를 저장할 수 있지만, 실행 위치와 운영 시 주의할 점이 다릅니다.
내장 PostgreSQL
앱과 DB가 처리 능력·메모리·저장 공간을 공유합니다. 별도 DB 자원 요금은 없으며, 인스턴스 중지·장애의 영향을 함께 받습니다.
별도 DB
앱과 분리된 DB에 접속합니다. 인스턴스 비용 외에 DB 비용이 추가되며, DB 용량과 운영 상태를 따로 관리합니다.
별도 DB를 발급해도 내장 PostgreSQL의 데이터가 자동으로 옮겨지지는 않습니다.
전환하려면 기존 데이터를 백업·이전하고, 프로젝트의 DB 연결 정보를 변경한 뒤 정상 동작을 확인해야 합니다. 사용하는 사람이 몇 명인지뿐 아니라 동시 접속, 저장량, 조회 빈도와 데이터 중요도를 함께 정리해 선택하십시오.
별도 DB 발급 전 확인
저장할 정보와 사용할 환경을 코딩 에이전트와 함께 정리합니다.
| 준비 항목 | 안내 |
|---|---|
| 선행 인스턴스 | DB를 사용할 프로젝트의 동일한 Staging 또는 Production 환경에 인스턴스가 발급되어 있는지 확인합니다. 인스턴스 신청·승인만 받은 상태라면 먼저 발급을 활성화합니다. |
| 환경 | 기능 검증용 정보는 Staging, 실제 사용자 정보는 Production에 저장합니다. |
| 저장할 정보 | 회원, 게시글, 예약 등 보관할 항목과 필요한 검색·수정 기능을 정리합니다. |
| 기존 DB와 전환 계획 | 내장 PostgreSQL을 이미 사용 중이라면 저장된 데이터와 연결 설정을 확인합니다. 별도 DB로 바꿀 경우 데이터 이전·백업 계획과 추가 비용을 먼저 검토합니다. |
별도 DB 발급 및 활성화
별도 DB를 선택한 경우의 절차입니다. 내장 PostgreSQL은 인스턴스 신청 시 함께 설치하며, 프로젝트 상세 → 인스턴스 → 해당 환경의 PostgreSQL에서 접속 정보를 확인합니다.
같은 환경의 인스턴스 발급을 확인한 뒤, 프로젝트 상세의 DB에서 발급을 선택합니다.
프로젝트와 환경이 정확한지 확인하고 신청을 제출합니다.
전자 결재 승인 후 프로젝트 상세에서 발급을 활성화합니다.
발급 정보를 프로젝트 환경 변수에 등록합니다.
활성화 후 확인
발급 카드의 연결 정보는 각각 다른 역할을 담당합니다.
| 연결 정보 | 의미 |
|---|---|
| Name | 프로젝트가 사용할 데이터베이스의 이름입니다. |
| Host | 데이터베이스가 위치한 주소입니다. |
| Port | 데이터베이스에 연결할 때 사용하는 통로 번호입니다. |
| User | 데이터베이스 연결 권한을 확인하는 사용자 이름입니다. |
| Password | 연결 권한을 확인하는 비밀값입니다. |
연결 정보는 코드가 아닌 환경 변수로 관리합니다.
Password는 Git 저장소, 메신저 또는 화면 캡처에 포함하지 마십시오.
인스턴스까지 정리할 때는 DB를 먼저 삭제합니다.
필요한 데이터를 백업한 뒤 DB 삭제를 신청하고, 승인 후 실제 삭제가 완료되었는지 확인합니다. 같은 환경의 별도 DB가 남아 있거나 삭제 중이면 인스턴스 삭제를 신청할 수 없습니다.
그룹웨어 SSO 연동
SSO란
프로젝트마다 새로운 비밀번호를 만들지 않고 그룹웨어를 통해 사용자의 신원을 확인합니다. 프로젝트는 전달받은 사용자 정보를 바탕으로 로그인 상태를 만들고, 필요한 경우 사용자별 접근 권한을 구분합니다.
코딩 에이전트에게 전달하기
실제 콜백 경로를 먼저 확인하세요. 발급 후 접속 정보는 직접 입력하며, Client Secret은 대화에 공유하지 마세요.
이 프로젝트에 그룹웨어 SSO를 연동하려고 해. 인증 서버는 https://groupware.plus-ex.com이야. 코드를 보고 서비스 주소와 실제 Redirect URI, 필요한 연동 규격을 확인해줘. 접속 정보는 내가 .env에 직접 입력할 테니 파일은 수정하지 말아줘.
로그인 처리 흐름
사용자는 프로젝트와 그룹웨어 사이를 이동하며 한 번의 인증을 완료합니다.
로그인 시작
콜백 처리·로그인 상태 생성
사내 계정 인증
선택 기준
프로젝트의 이용 대상과 계정 체계에 따라 SSO 연동 여부를 결정합니다.
| 프로젝트의 상황 | 권장 방식 |
|---|---|
| PlusX 구성원만 이용하고 사내 계정으로 사용자를 확인해야 하는 경우 | 그룹웨어 SSO를 연동합니다. |
| 로그인 없이 누구나 이용하는 경우 | SSO를 신청하지 않아도 됩니다. |
| 외부 고객의 가입이나 별도 멤버십을 운영하는 경우 | 프로젝트에 별도의 회원가입과 인증 기능을 구현해야 합니다. |
SSO 로그인과 이용 권한 제한은 별개입니다.
SSO는 사용자의 신원을 확인하는 기능입니다. Station의 공개 범위는 표시용 정보이며, 선택만으로 SSO 연동이나 실제 이용 권한이 자동으로 설정되지는 않습니다.
특정 직급만 이용하게 하거나 특정 멤버만 허용하려면, 프로젝트 담당자가 SSO를 직접 연동하고 로그인한 사용자에 따라 접근을 허용·차단하는 기능도 프로젝트 내부에 별도로 구현해야 합니다. 메뉴와 데이터의 접근 범위도 같은 기준으로 제한합니다.
연동 전 확인
SSO 발급에 필요한 선행 인스턴스와 환경별 예외를 확인한 뒤, 인증 서버 주소와 로그인 후 이동할 주소를 준비합니다.
| 준비 항목 | 안내 |
|---|---|
| Dev | 내 컴퓨터에서 개발 중인 프로젝트의 로그인을 검증할 때 사용하며, 인스턴스 없이 SSO를 발급할 수 있습니다. localhost와 127.0.0.1은 내 컴퓨터를 가리키는 주소입니다. 예: http://localhost:3000/ 또는 http://127.0.0.1:8000/ 신청 화면의 기본값은 http://127.0.0.1:8000/입니다. 실제 프로젝트가 열리는 주소와 포트 번호에 맞게 직접 수정합니다. |
| Staging·Production | 같은 프로젝트·같은 환경의 인스턴스가 먼저 발급되어 있어야 SSO를 신청할 수 있습니다. 인스턴스 신청·승인만 받은 상태라면 먼저 발급을 활성화합니다. 예를 들어 Production SSO에는 Production 인스턴스가 필요하며, 발급된 인스턴스 도메인이 서비스 도메인으로 연결됩니다. 인스턴스 없이 발급할 수 있는 예외는 Dev SSO뿐입니다. |
| 서비스 도메인 | 로그인을 시작하는 프로젝트의 기본 주소입니다. Dev는 신청할 때 직접 입력할 수 있으며, 발급 후에도 프로젝트 상세의 SSO 카드 → 수정에서 주소와 포트 번호를 결재 없이 변경할 수 있습니다. Staging·Production은 발급된 인스턴스 도메인으로 고정됩니다. |
| 인증 서버 주소 (Provider URL) | 사내 계정 로그인을 처리하는 그룹웨어 주소입니다. 내 프로젝트의 서비스 도메인과는 다릅니다. 주소: https://groupware.plus-ex.com Dev·Staging·Production 모두 같은 주소를 사용합니다. 프로젝트 상세의 SSO 연동 가이드에 따라 .env의 OAUTH2_PROVIDER_URL에 설정하며, 발급 신청 폼의 서비스 도메인에 입력하는 값은 아닙니다. |
| Redirect URI | 그룹웨어의 인증 결과를 받아 로그인 처리를 마무리하는 프로젝트의 콜백 주소입니다. 로그인 후 보여줄 메인 화면 주소나 그룹웨어 주소와는 다릅니다. |
| Post-Logout URI | 로그아웃 완료 후 사용자를 이동시킬 주소입니다. |
로컬 접속 주소와 SSO에 등록한 주소를 일치시킵니다.
localhost와 127.0.0.1은 같은 컴퓨터를 가리켜도 서로 다른 주소로 구분됩니다. 로그인에 사용할 주소를 하나로 정하고, http:// 또는 https://와 포트 번호까지 맞추십시오.
주소를 수정한 뒤에는 프로젝트의 로그인·로그아웃 설정도 함께 확인합니다.
Redirect URI 설정 확인
SSO에 등록한 Redirect URI와 프로젝트가 로그인 요청에 사용하는 주소가 다르면 인증이 거부되거나 프로젝트로 돌아오지 못할 수 있습니다. 먼저 코딩 에이전트와 프로젝트의 실제 콜백 경로를 확인합니다.
| 확인 항목 | 예시와 설정 방법 |
|---|---|
| SSO 카드에서 수정 | 프로젝트 상세 → SSO → 해당 환경의 수정에서 변경합니다. Redirect URI 입력란 앞에 서비스 도메인이 표시되므로, 뒤쪽에는 /oauth/callback처럼 경로만 입력합니다. 도메인을 다시 붙이지 않습니다. |
| 프로젝트 설정 | SSO 연동 가이드의 OAUTH2_REDIRECT_CALLBACK_URI에는 경로만이 아니라 완성된 전체 주소를 설정합니다. SSO 카드의 Redirect URI와 프로젝트가 실제 로그인 요청에 사용하는 주소를 동일하게 맞춥니다. |
| 자주 틀리는 부분 | http와 https, localhost와 127.0.0.1, 포트 번호, 콜백 경로의 철자·대소문자 및 마지막 /까지 확인합니다. 예를 들어 /oauth/callback과 /oauth/callback/을 섞어 쓰지 않습니다. Dev·Staging·Production의 주소와 Client ID도 같은 환경의 값인지 확인합니다. |
한쪽 주소만 바꾸지 말고 SSO 설정과 프로젝트 설정을 함께 맞춥니다.
프로젝트 설정을 수정한 뒤에는 변경값이 실행 중인 앱에 반영되었는지 확인하고, 필요한 경우 재시작·재배포한 후 로그인을 다시 시도합니다.
신청 및 연결
승인 후 발급된 값을 프로젝트 설정에 연결하고 로그인과 로그아웃을 검증합니다.
프로젝트 상세의 SSO에서 환경과 서비스 도메인을 확인합니다.
연결할 프로젝트와 환경이 정확한지 확인하고 제출합니다.
발급이 완료되면 SSO 연동 가이드에 따라 인증 서버 주소와 발급값을 환경 변수에 등록합니다.
시크릿 모드에서 로그인과 로그아웃을 각각 확인합니다.
승인 후 확인
발급 카드에 표시된 값의 역할을 확인한 후 프로젝트에 연결합니다.
| 발급 정보 | 의미 |
|---|---|
| Client ID | 어떤 프로젝트의 로그인 요청인지 구분하는 공개 식별값입니다. |
| Client Secret | 프로젝트가 그룹웨어에 자신을 증명할 때 사용하는 비밀값입니다. |
| Redirect URI | 인증 결과를 처리하는 프로젝트의 콜백 주소입니다. 프로젝트의 실제 로그인 요청에 사용하는 주소와 일치해야 합니다. |
| Post-Logout URI | 로그아웃 후 사용자가 이동하는 주소입니다. |
Client Secret은 비밀번호와 같은 민감 정보입니다.
코드나 Git 저장소에 포함하지 않고 환경 변수로 관리하십시오.
연결 주소는 SSO 카드의 수정 버튼에서 변경합니다.
Redirect URI와 Post-Logout URI의 경로는 모든 환경에서, 서비스 도메인은 Dev에서만 수정할 수 있습니다.
별도 결재 없이 저장되므로 프로젝트의 설정도 같은 값으로 맞추고 로그인·로그아웃을 다시 확인합니다.
Station 공개
Station이란
프로젝트 이름, 설명, 이미지, 이용 방법 및 공개 범위 표시를 등록하여 사내 구성원에게 소개합니다. 인스턴스로 공개한 웹 프로젝트뿐 아니라 별도 자원이 필요하지 않은 설치형 프로그램도 릴리즈할 수 있습니다.
공개 방식 확인
프로젝트 형태에 따라 Station 릴리즈 전에 준비할 항목이 달라집니다.
| 프로젝트 형태 | 릴리즈 전 준비 |
|---|---|
| 인스턴스로 실행하는 웹 프로젝트 | 인스턴스가 활성 상태이고 접속 도메인에서 주요 기능이 동작하는지 확인합니다. |
| 설치형 프로그램 | 설치 파일과 지원 운영체제를 확인합니다. 인스턴스 및 DB 발급은 필수가 아닙니다. |
Station은 프로젝트를 직접 실행하는 공간이 아닙니다.
웹 프로젝트는 등록할 링크가 정상적으로 열리는지, 설치형 프로그램은 첨부 파일이 정상적으로 설치되는지 먼저 확인합니다.
릴리즈 정보 준비
처음 접하는 구성원도 프로젝트의 목적과 이용 방법을 이해할 수 있도록 작성합니다.
| 준비 항목 | 안내 |
|---|---|
| 기본 분류 | 카테고리, 접근 권한(공개 범위 표시), 배포 형태, 지원 기기 및 운영체제를 선택합니다. |
| 이용 경로 | 웹 프로젝트의 접근 링크 또는 설치형 프로그램의 첨부 파일을 준비합니다. |
| 소개 문구 | 프로젝트의 목적이 드러나는 한 줄 소개와 주요 기능을 설명하는 상세 내용을 작성합니다. |
| 버전 정보 | 최초 버전과 주요 변경 내용을 구성원이 이해할 수 있는 문장으로 작성합니다. |
이미지 준비
Station에 표시할 이미지의 용도와 필수 여부를 확인합니다.
| 준비 항목 | 안내 |
|---|---|
| 프로젝트 아이콘 · 필수 | 프로젝트를 식별하는 정사각형 이미지 |
| 썸네일 · 필수 | Station 목록 카드의 대표 이미지 |
| 스크린샷 · 필수 | 실제 사용 화면 · 1장 이상 |
| PWA 아이콘 · 선택 | PWA 홈 화면에 사용하는 아이콘 |
| 메인 이미지 · 필수 | Station 상세 상단에 사용하는 이미지 |
릴리즈 절차
Station 릴리즈는 1차와 2차 전자 결재가 모두 완료된 후 공개됩니다.
프로젝트 상세의 Station에서 기본 정보와 이용 경로를 입력합니다.
아이콘, 대표 이미지 및 스크린샷을 등록합니다.
입력 내용을 확인하고 Station 릴리즈를 제출합니다.
1차와 2차 승인이 완료되면 Station에 공개됩니다.
공개 후 관리
변경하려는 항목에 따라 신청 유형을 구분합니다.
| 변경 상황 | 진행 방법 |
|---|---|
| 한 줄 소개, 상세 설명 또는 기본 정보 변경 | 정보 수정 신청을 제출합니다. |
| 아이콘, 대표 이미지 또는 스크린샷 변경 | 이미지 수정 신청을 제출합니다. |
| 버전 및 변경 이력 기록 | 프로젝트 상세의 Station에서 버전 번호와 변경 내용(릴리즈 노트)을 추가합니다. 버전 추가는 이력을 기록하는 기능이며, 코드 배포나 설치 파일 교체는 별도로 진행해야 합니다. |
| 공개 상태 확인 | Station에서 프로젝트 상세 정보, 최신 버전 및 이용 경로를 확인합니다. |
공개 범위 선택만으로 SSO나 실제 접근 제한이 적용되지는 않습니다.
Station의 ‘접근 권한’은 공개 범위를 안내하는 표시용 정보입니다.
SSO 로그인 연동과 사용자별 접근 제한은 프로젝트 담당자가 직접 설정·구현해야 합니다.
전자 결재
전자 결재란
인스턴스·DB 발급 및 Station 릴리즈처럼 공용 자원이나 공개 상태에 영향을 주는 작업은 승인 후 진행됩니다. 프로젝트 생성과 일부 설정 수정은 결재 없이 처리되므로 작업별 구분을 확인합니다.
결재 대상
작업의 영향 범위에 따라 전자 결재 필요 여부가 달라집니다.
| 작업 | 처리 방식 |
|---|---|
| 인스턴스·DB 발급 | 결재 승인 후 프로젝트 상세에서 발급을 활성화해야 합니다. |
| SSO 발급 | 결재 승인 후 자동으로 발급이 진행됩니다. 발급된 값을 프로젝트에 연결해야 합니다. |
| 인스턴스·DB·SSO 삭제 | 결재 승인 후 삭제가 진행됩니다. 신청 전에 대상과 영향을 확인합니다. |
| Station 릴리즈·정보 수정·이미지 수정·삭제 | 1차와 2차 결재가 모두 승인된 후 반영됩니다. |
| 인스턴스 중지 | Station에 게시된 프로젝트는 결재가 필요합니다. 미게시 프로젝트는 확인 후 결재 없이 중지를 실행합니다. |
| 프로젝트 생성·정보 수정, 인스턴스 시작 | 별도 결재 없이 처리됩니다. 인스턴스 시작은 실행 후 상태가 바뀔 때까지 기다립니다. |
| SSO 연결 주소 수정 | 별도 결재 없이 저장됩니다. Dev 도메인과 각 환경의 로그인·로그아웃 경로를 수정할 수 있습니다. |
| Station 버전 추가·내용 수정 | 별도 결재 없이 버전 번호와 변경 이력을 기록하며, 내용 수정은 릴리즈 노트를 변경하는 작업입니다. 코드 배포나 설치 파일 교체는 포함되지 않습니다. |
상태 확인
현재 상태에 따라 기다리거나 후속 작업을 진행합니다.
| 상태 | 의미와 다음 작업 |
|---|---|
| 대기 | 담당자가 신청 내용을 검토 중입니다. 동일한 신청을 반복하지 않고 현재 결재 단계를 확인합니다. |
| 1차 승인 | 2단계 결재 대상은 최종 승인 전까지 변경 사항이 반영되지 않습니다. |
| 최종 승인 | 신청이 허용된 상태입니다. 자원 종류에 따라 활성화 또는 연결 작업을 진행합니다. |
| 반려 | 상세 사유를 확인하고 요청된 내용을 보완하여 다시 신청합니다. |
신청 및 처리
신청 대상과 환경을 확인한 후 진행 상태에 맞게 처리합니다.
프로젝트, 환경, 신청 유형 및 변경 대상을 확인합니다.
작업 목적과 필요한 이유를 구체적으로 작성하여 제출합니다.
전자 결재에서 현재 승인 단계와 반려 사유를 확인합니다.
최종 승인 후 자원을 활성화하거나 발급값을 연결합니다.
승인 후 진행
승인만으로 모든 작업이 완료되는 것은 아니므로 신청 유형별 후속 단계를 확인합니다.
승인과 실제 작업 완료는 다릅니다.
자원 중지·삭제는 별도 활성화 없이 진행되므로 실제 완료 상태를 확인합니다. Station 게시가 SSO 로그인이나 사용자별 접근 제한을 대신 구현하지는 않습니다.
자원 정리
프로젝트 전체를 정리할 때는 공개 정보와 로그인·저장 기능의 영향을 먼저 확인합니다. 같은 환경의 별도 DB 삭제 완료는 인스턴스 삭제의 필수 선행 조건입니다.
공개 정보와 이용 중인 접근 경로의 영향을 먼저 확인합니다.
사용하지 않을 SSO를 정리하고, 필요한 데이터를 백업한 뒤 별도 DB 삭제를 완료합니다.
같은 환경의 별도 DB가 삭제된 것을 확인한 뒤 인스턴스 삭제를 신청합니다.
진행 중인 신청과 남은 자원이 없는지 확인한 후 삭제합니다.
DB 삭제 신청이나 승인만으로는 인스턴스를 삭제할 수 없습니다.
같은 프로젝트·같은 환경의 별도 DB가 실제로 삭제된 뒤 인스턴스 삭제를 신청합니다. 삭제 중이면 완료될 때까지 기다립니다.
삭제한 항목은 복구할 수 없으므로 필요한 데이터를 미리 백업하고, 대상 환경과 함께 삭제되는 항목을 확인하십시오.
문제 해결
문제 확인 방법
프로젝트명, 환경, 현재 상태, 오류 문구 및 문제가 시작된 시점을 기록하면 원인을 빠르게 찾을 수 있습니다. 새로고침이나 같은 작업의 반복만으로 해결되지 않는 경우 아래에서 해당하는 증상을 펼쳐 확인합니다.
민감 정보는 화면 캡처나 대화에 포함하지 마십시오.
Client Secret, Password 및 PEM 키의 내용은 관리자나 코딩 에이전트에게도 그대로 전달하지 않습니다.
프로젝트 실행과 배포
다른 사용자가 웹 프로젝트에 접속할 수 없음
프로젝트가 내 컴퓨터에서만 실행 중인지 확인합니다. 웹 프로젝트는 인스턴스로 배포해야 합니다.
도메인은 열리지만 주요 기능이 작동하지 않음
인스턴스가 활성 상태인지, 최신 코드와 환경 변수가 연결되었는지 확인합니다.
설치형 프로그램의 실행 파일을 찾을 수 없음
Station에 등록된 첨부 파일과 지원 운영체제를 확인합니다. 설치형 프로그램은 인스턴스가 없어도 릴리즈할 수 있습니다.
자원 발급과 연결
발급 버튼이 비활성 상태임
동일한 신청이 진행 중이거나 선행 자원이 없을 수 있습니다. 버튼에 마우스를 올려 표시되는 사유를 확인합니다.
DB·SSO 발급 환경을 선택할 수 없음
별도 DB와 Staging·Production SSO는 같은 프로젝트·같은 환경의 인스턴스를 먼저 발급해야 신청할 수 있습니다.
다른 환경에만 인스턴스가 있거나 신청·승인만 받은 상태인지 확인합니다. Dev SSO는 인스턴스 없이 신청할 수 있습니다.
승인 후 자원이 표시되지 않음
인스턴스와 DB는 프로젝트 상세에서 발급을 활성화해야 합니다. 활성화를 시작한 후 상태를 다시 확인합니다.
DB에 연결할 수 없음
DB와 인스턴스의 환경이 같은지 확인하고 Host, Port, Name 및 User가 정확한지 점검합니다. Password 앞뒤의 공백도 확인합니다.
PEM 키를 분실함
PEM 키는 다시 다운로드할 수 없습니다. 관리자와 영향 범위를 확인한 후 인스턴스 재생성을 검토합니다.
SSO와 Station
Redirect URI 오류로 로그인이 진행되지 않음
SSO 카드에 표시된 Redirect URI와 프로젝트가 로그인 요청에 사용하는 전체 주소를 비교합니다.
http/https, localhost/127.0.0.1, 포트, 경로·대소문자·끝 슬래시 및 Client ID의 환경을 확인합니다. 변경 시 SSO 설정과 프로젝트 설정을 함께 맞춥니다.
SSO 로그인 후 프로젝트로 돌아오지 않거나 404가 표시됨
등록된 콜백 경로가 프로젝트에 실제로 구현되어 있는지, 해당 주소와 포트에서 앱이 실행 중인지 확인합니다.
메인 화면 주소를 콜백 주소로 등록하지 않았는지도 점검하고, 변경한 설정을 실행 중인 앱에 반영한 뒤 다시 로그인합니다.
SSO 로그인 또는 권한 확인에 실패함
Client ID와 Client Secret이 동일한 환경의 값인지 확인합니다. Client Secret에 공백이나 따옴표가 포함되지 않도록 주의합니다.
Station 승인 후 프로젝트가 보이지 않음
릴리즈가 최종 승인 상태인지 확인합니다. 승인 후에도 보이지 않는다면 관리자에게 Station 게시 상태 확인을 요청합니다.
공개 범위를 선택했는데 로그인이 적용되지 않음
Station의 공개 범위는 표시용 정보이며 SSO를 자동으로 설정하지 않습니다. 프로젝트에 SSO 로그인을 직접 연동하고, 사용자별 접근 제한이 필요한 경우 별도로 구현합니다.
Station에서 프로젝트를 실행할 수 없음
Station은 프로젝트를 직접 실행하지 않습니다. 웹 프로젝트는 등록된 도메인과 자원 상태를, 설치형 프로그램은 첨부 파일과 실행 환경을 확인합니다.
전자 결재와 삭제
신청이 반려됨
전자 결재 상세에서 사유를 확인하고 요청된 내용을 보완하여 다시 신청합니다. 이전 신청을 변경 없이 반복하지 않습니다.
프로젝트를 삭제할 수 없음
진행 중인 신청과 Station 공개 정보를 먼저 정리하고, 연결된 SSO·DB 및 인스턴스가 남아 있는지 확인합니다.
인스턴스를 삭제할 수 없음
같은 프로젝트·같은 환경의 별도 DB가 남아 있는지 확인합니다.
DB 삭제를 먼저 신청하고 실제 삭제 완료 후 인스턴스 삭제를 신청합니다. DB 삭제가 승인 대기·삭제 중인 상태라면 아직 진행할 수 없습니다.
어떤 자원부터 삭제해야 하는지 알 수 없음
프로젝트 전체 정리는 Station → SSO·DB → 인스턴스 → 프로젝트 순서로 연결 관계와 영향을 확인합니다.
특히 같은 환경의 별도 DB 삭제 완료 후에만 인스턴스를 삭제할 수 있습니다.
삭제 팝업에 여러 항목이 표시됨
함께 정리되는 환경, 도메인 및 연결 자원을 모두 확인합니다. 삭제 후에는 복구할 수 없습니다.
해결되지 않는 경우
관리자 또는 코딩 에이전트가 동일한 문제를 확인할 수 있도록 아래 정보를 정리합니다.
| 기록할 정보 | 예시 |
|---|---|
| 위치 | 프로젝트명, 메뉴명 및 Staging·Production 등의 환경 |
| 수행한 작업 | 선택한 버튼과 입력한 항목을 발생 순서대로 기록 |
| 표시된 결과 | 현재 상태, 오류 문구 및 문제가 발생한 시각 |
| 재현 여부 | 새로고침 후 같은 작업을 수행했을 때 동일하게 발생하는지 확인 |
용어 정리
프로젝트와 배포
프로젝트를 만들고 다른 사용자가 이용할 수 있도록 준비하는 과정에서 사용하는 기본 용어입니다.
| 용어 | 의미 |
|---|---|
| 프로젝트 | 하나의 배포 대상에 필요한 자원, 접근 정보 및 Station 정보를 함께 관리하는 단위입니다. |
| 배포 | 내 컴퓨터에서 만든 프로젝트를 다른 사용자가 웹으로 접속하거나 설치하여 이용할 수 있는 상태로 전환하는 과정입니다. |
| 프론트엔드 | 버튼, 입력창, 목록 및 화면 이동처럼 사용자가 직접 확인하고 조작하는 영역입니다. |
| 백엔드 | 로그인 확인, 정보 처리와 저장 및 자동 작업처럼 화면 뒤에서 실행되는 기능입니다. |
| API | 화면과 기능 또는 서로 다른 시스템이 정해진 규칙에 따라 정보를 주고받는 연결 방식입니다. |
환경과 주소
환경은 같은 프로젝트를 개발·사전 검증·실제 운영 용도로 나누어 실행하는 구분입니다. 테스트 중인 변경이 실제 이용자와 운영 데이터에 영향을 주지 않도록 접속 주소와 연결 설정을 구분합니다.
내 컴퓨터에서 코드를 작성하고 기능을 시험합니다. 예약 화면을 만들고 저장 기능을 확인하는 단계입니다.
http://localhost:3000/http://127.0.0.1:8000/
Dev 인스턴스·별도 DB는 미제공입니다. Dev SSO는 인스턴스 없이 신청할 수 있습니다.
별도 인스턴스에 배포해 구성원과 전체 이용 흐름을 점검합니다. 테스트용 예약 데이터로 검증합니다.
https://stage.team-book.plusxdev.comStaging 인스턴스 발급 후 필요한 DB·SSO를 연결합니다. 운영 DB 대신 테스트 DB를 사용합니다.
실제 이용자와 업무 데이터가 있는 환경입니다. 검증된 기능을 배포하며 변경·중지·삭제에 주의합니다.
https://team-book.plusxdev.comProduction 인스턴스 발급 후 필요한 DB·SSO를 연결합니다. 테스트 설정이 섞이지 않았는지 확인합니다.
| 용어 | 의미 |
|---|---|
| DNS | 도메인 이름을 인스턴스의 IP 주소와 연결해 접속할 위치를 찾도록 하는 시스템입니다. |
| HTTPS | 브라우저와 서버 사이의 통신을 암호화하는 방식입니다. 사용자 권한 설정이나 프로젝트 배포를 대신하지는 않습니다. |
| SSL/TLS 인증서 | 접속한 도메인의 서버임을 확인하고 HTTPS 암호화 통신을 구성하는 데 사용하는 전자 인증서입니다. |
| 도메인 | 사용자가 웹 프로젝트에 접속할 때 입력하거나 선택하는 주소입니다. |
| localhost·127.0.0.1 | 외부 인스턴스가 아닌 내 컴퓨터를 가리키는 주소입니다. 로컬에서 개발 중인 프로젝트에 접속할 때 사용합니다. 두 주소는 같은 컴퓨터를 가리켜도 SSO 설정에서는 서로 다른 주소로 구분하므로 실제 접속 주소와 등록한 주소를 일치시킵니다. |
| 포트(Port) | 같은 컴퓨터에서 실행 중인 서비스를 구분하는 번호입니다. 예를 들어 http://localhost:3000/에서 3000이 포트 번호입니다. 프로젝트가 실제로 사용하는 번호에 맞춰 입력합니다. |
| 슬러그(Slug) | 도메인에 포함되어 프로젝트를 구분하는 이름입니다. 예를 들어 team-book의 운영 주소는 team-book.plusxdev.com, 스테이징 주소는 stage.team-book.plusxdev.com입니다. 한 프로젝트의 모든 환경이 공유하며, 변경하려면 해당 프로젝트의 인스턴스를 모두 삭제한 후 다시 발급해야 합니다. |
| 환경 변수 | 프로젝트가 실행될 때 사용하는 이름과 값 형태의 설정입니다. 접속 주소, Password 및 인증 정보처럼 환경마다 다르거나 코드에 직접 작성하면 안 되는 값을 전달할 때 사용합니다. |
| .env 파일 | 환경 변수에 사용할 이름과 값을 모아두는 설정 파일입니다. 환경 변수가 설정값이라면 .env는 그 값을 적어두는 파일입니다. 비밀번호와 Client Secret이 포함된 파일은 Git 저장소에 올리거나 외부에 공유하지 않습니다. |
Dev → Staging → Production은 권장 작업 순서이며, 자동 전환을 뜻하지 않습니다.
Developers에서 환경을 선택하거나 자원을 발급하는 것만으로 코드와 DB 데이터가 다른 환경에 복사되지는 않습니다. 배포와 DB·SSO 연결은 환경별로 진행하고, 테스트 데이터와 운영 데이터를 분리하십시오.
Staging·Production 주소는 team-book 슬러그를 사용한 예시입니다. 로컬 포트와 발급 도메인은 프로젝트에 맞게 확인합니다.
발급 자원
프로젝트의 실행, 공개 및 정보 저장에 필요한 자원입니다.
| 용어 | 의미 |
|---|---|
| 인스턴스 | 내 컴퓨터가 꺼져 있어도 프로젝트를 계속 실행하는 원격 컴퓨터입니다. 서버 기능이 있는 웹 프로젝트에 사용합니다. |
| DB | 회원, 게시글 및 예약처럼 일정한 항목으로 나뉘는 정보를 표 구조로 저장하고 조회하는 관계형 데이터베이스입니다. |
| PostgreSQL | 회원 정보·게시글·예약 내역 같은 데이터를 저장하고 조회·수정하는 DB 소프트웨어입니다. Developers의 인스턴스 내장 DB와 별도 DB 모두 PostgreSQL을 사용합니다. |
| 발급 활성화 | 인스턴스·DB의 발급 결재가 승인된 뒤, 프로젝트 상세에서 실제 자원 생성을 시작하는 단계입니다. 결재 승인만으로 자원이 생성되지는 않으며, 활성화가 완료되어도 프로젝트 코드의 배포나 연결 작업은 별도로 진행해야 합니다. |
| IP 주소 | 네트워크에서 인스턴스나 DB의 위치를 구분하는 숫자 형식의 주소입니다. |
| SSH | 내 컴퓨터에서 원격 인스턴스에 안전하게 접속하여 명령을 실행하는 방식입니다. 인스턴스 연동 가이드에서는 PEM 키로 접속 권한을 확인합니다. |
| PEM 키 | 인스턴스에 안전하게 접속할 때 사용하는 1회 발급 파일입니다. 다운로드 후 연동 가이드의 ‘PEM Key 보관하기’ 안내에 따라 ~/.ssh/로 옮기고 파일 권한을 설정합니다. 분실 시 다시 다운로드할 수 없습니다. |
| ~/.ssh/ | 개인 홈 폴더 안에 있는 SSH 키와 접속 설정을 보관하는 폴더입니다. ~는 개인 홈 폴더를 뜻합니다. 다운로드한 PEM 키는 연동 가이드에 따라 이곳으로 옮기고, 본인만 읽을 수 있도록 파일 권한을 설정합니다. |
인스턴스 및 DB는 모든 프로젝트에 필요한 자원이 아닙니다.
프로젝트의 실행 방식과 기능을 확인한 후 필요한 자원만 발급합니다.
로그인과 인증
그룹웨어 계정으로 안전하게 로그인하기 위해 사용하는 용어입니다.
| 용어 | 의미 |
|---|---|
| SSO | 별도의 회원가입 없이 그룹웨어 계정으로 프로젝트에 로그인하는 기능입니다. |
| 서비스 도메인 | 내가 만든 프로젝트가 열리는 기본 주소입니다. 예를 들어 Dev에서는 http://localhost:3000, 운영에서는 https://team-book.plusxdev.com을 사용할 수 있습니다. 로그인을 처리하는 그룹웨어의 인증 서버 주소와는 다릅니다. |
| 인증 서버 주소 (Provider URL) | 사내 계정 로그인을 처리하는 그룹웨어 주소입니다. Dev·Staging·Production 모두 https://groupware.plus-ex.com을 사용하며, 프로젝트의 OAUTH2_PROVIDER_URL에 설정합니다. 발급 신청 폼의 서비스 도메인에 입력하는 값은 아닙니다. |
| Client ID | SSO가 어떤 프로젝트의 로그인 요청인지 구분할 때 사용하는 공개 식별값입니다. |
| Client Secret | 프로젝트가 SSO에 자신을 증명할 때 사용하는 비밀값입니다. Password와 같이 외부에 공개해서는 안 됩니다. |
| Redirect URI | SSO 인증 결과를 받아 프로젝트의 로그인 처리를 마무리하는 콜백 주소입니다. 예: http://127.0.0.1:8000/oauth/callback 실제 프로젝트의 콜백 경로를 사용하고, SSO에 등록된 값과 로그인 요청의 전체 주소를 일치시켜야 합니다. 로그인 후 보여줄 메인 화면 주소와는 다릅니다. |
| Post-Logout URI | SSO 로그아웃을 마친 사용자를 이동시킬 정확한 주소입니다. |
Station과 전자 결재
완성된 프로젝트를 사내에 공개하고 변경 사항을 승인받을 때 사용하는 용어입니다.
| 용어 | 의미 |
|---|---|
| Station | 완성된 사내 프로젝트를 소개하고 구성원이 찾아 이용할 수 있도록 연결하는 서비스 허브입니다. 프로젝트의 SSO 로그인이나 실제 접근 제한을 대신 설정하지는 않습니다. |
| 릴리즈 | 프로젝트의 소개 정보, 이용 경로 또는 설치 파일을 Station에 제출하여 공개하는 절차입니다. |
| 버전 | 프로젝트의 변경 상태를 구분하기 위한 번호입니다. Station의 버전 추가는 번호와 변경 이력을 기록하는 기능으로, 실제 코드 배포나 설치 파일 교체는 별도로 진행합니다. |
| 접근 권한 (Station 공개 범위) | Station에 프로젝트의 공개 범위를 안내하기 위한 표시용 정보입니다. 선택한 값이 SSO 설정이나 실제 이용 권한을 자동으로 적용하지는 않습니다. 로그인 연동과 사용자별 접근 제한은 프로젝트 담당자가 직접 설정·구현해야 합니다. |
| 전자 결재 | 공용 자원과 사내 공개 정보의 신청 내용을 담당자가 검토하고 승인하는 절차입니다. |
| 2단계 결재 | 1차 담당자가 신청 내용을 검토한 후 최고 관리자가 최종 승인하는 절차입니다. |