온프레미스 설치 마법사

Ubuntu 24.04 LTS 서버에서 저장소의 on-premise/ 폴더에 있는 설치 마법사를 사용합니다. 터미널 질문에 답하면 별도 설치 폴더에 설정을 저장하고 PostgreSQL·Redis·S3 호환 저장소를 설치합니다. 각 항목은 기존 외부 서비스를 사용하는 방식도 선택할 수 있습니다.

어디에서 실행하는가

Windows PC는 SSH 접속, 사전 점검과 파일 전달에 사용합니다. Docker 설치, 소스 빌드, DB 복원, 앱 기동과 관리자 생성은 모두 대상 Ubuntu 서버의 SSH 터미널에서 실행합니다. 이 문서의 powershell 블록만 Windows PC 명령이며, 별도 표시가 없는 bash 블록은 대상 서버 명령입니다.

작업	실행 위치	소스 필요 여부
원격 사전 점검	Windows PC	필요 없음
저장소 clone·Docker 설치·앱 빌드	Ubuntu 서버	서버에 Git 작업 복사본 필요
DB 복원·앱 운영	Ubuntu 서버	빌드 후 원본 작업 복사본 불필요
브라우저 검증	Windows PC 또는 사내 사용자 PC	필요 없음

기본 설치에서는 Ubuntu 서버가 승인 저장소를 직접 clone하므로 Windows PC에 IntelliDesk 전체 소스를 받을 필요가 없습니다. 서버가 저장소에 접근할 수 없을 때만 승인된 Git bundle과 설치 DB 덤프를 PC에서 scp로 전달합니다. 앱 빌드는 Git HEAD를 확인하므로 .git 정보가 없는 일반 ZIP 폴더는 사용할 수 없습니다.

현재 신규 DB 준비 범위

PostgreSQL과 pgvector 설치는 자동화되어 있습니다. 하지만 현재 앱의 db:init이 참조하는 기본 스키마 파일이 저장소에 없어, 앱 실행에는 설치 환경에 맞게 준비된 DB가 필요합니다. 빈 DB에서는 앱 기동을 중단합니다. 고객 데이터와 기존 운영 서버 연결정보가 없는 설치용 DB를 준비한 뒤 진행하세요.

사전 준비

• Ubuntu 24.04 LTS와 sudo 권한을 준비합니다.
• 시작 기준으로 4 vCPU, 8GB RAM 이상과 빌드·이미지용 여유 공간 30GB 이상을 확보하고 데이터 규모에 맞게 조정합니다.
• 사내 DNS에 앱·테넌트·S3 주소를 등록합니다.
• 최초 설치에 필요한 GitHub, npm, Docker 이미지 및 APT 저장소 접근을 준비합니다. 폐쇄망 패키지 반입은 별도입니다.
• S3 접근 방식과 공개 이미지 정책은 온프레미스 파일 스토리지를 확인합니다.

설치를 대리인이 수행한다면 on-premise/Invoke-OnPremisePreflight.ps1 한 파일과 on-premise/DELEGATE-CHECKLIST.md를 전달합니다. PowerShell 파일 안에 원격 점검기가 포함되어 있어 별도 실행 파일은 필요하지 않습니다.

Set-ExecutionPolicy -Scope Process Bypass
Unblock-File C:\Work\Invoke-OnPremisePreflight.ps1
& C:\Work\Invoke-OnPremisePreflight.ps1

스크립트가 서버 IP, SSH 아이디, 포트, 인증 방식과 선택적인 DNS 정보를 차례로 묻습니다. 최초 접속에서 표시되는 호스트 키 지문은 서버 관리자에게 확인합니다. 결과 파일의 FAIL 항목은 설치 전에 해결하고 WARN 항목은 담당자와 검토합니다. 점검 보고서에는 비밀번호, API 키, DB 암호화 키와 SSH 개인키를 기록하지 않습니다.

마법사 실행

Windows PC에서 ssh <SSH-아이디>@<서버-IP>로 접속한 뒤, 아래 명령을 Ubuntu 서버 터미널에서 실행합니다. 승인된 GitHub 저장소를 서버에 내려받고 배포할 태그 또는 커밋으로 이동합니다. 토큰은 저장소 URL에 직접 넣지 않습니다.

sudo apt-get update
sudo apt-get install -y git python3 openssl ca-certificates
git clone <승인된-저장소-URL> intellidesk-source
cd intellidesk-source
git checkout <배포할-태그-또는-커밋>
sudo bash on-premise/install-docker.sh
sudo bash on-premise/install.sh

서버가 저장소에 접근하지 못하면 Windows PC PowerShell에서 승인된 Git bundle과 DB 덤프를 전달합니다.

scp C:\Work\intellidesk-release.bundle <SSH-아이디>@<서버-IP>:/tmp/
scp C:\Work\intellidesk-install.dump <SSH-아이디>@<서버-IP>:/tmp/

Ubuntu 서버에서는 bundle을 Git 저장소로 clone한 뒤 같은 설치 절차를 진행합니다.

git clone /tmp/intellidesk-release.bundle ~/intellidesk-source
cd ~/intellidesk-source
git checkout <배포할-태그-또는-커밋>

질문	기본값
설치 폴더	/opt/intellidesk
앱 접속 주소	http://intellidesk.internal:8080
테넌트 기본 도메인	intellidesk.internal
PostgreSQL·Redis·S3	이 서버에 설치
DB 이름·사용자	intellidesk
S3 주소·버킷	http://intellidesk.internal:8333, intellidesk
SSO 포트·관리자 이메일	9000, admin@intellidesk.internal
비밀번호·내부 비밀키	설치별 무작위 생성, 화면에 표시하지 않음
회원가입 이메일 인증	기본적으로 사용 안 함, Resend 구성 후 활성화 가능

Enter로 기본값을 사용합니다. SSO 관리자와 IntelliDesk 앱 관리자는 별개입니다. AI 키는 나중에 설정할 수 있습니다. 기존 암호화된 DB를 복원한다면 기존 ENCRYPTION_KEY를 입력해야 합니다.

내장 PostgreSQL·Redis는 Docker 내부에서만 접근합니다. 기존 호스트의 DB를 사용할 때는 컨테이너 내부의 localhost 대신 host.docker.internal을 사용합니다. S3 파일 API와 앱·SSO 포트는 사내에서 접근 가능하도록 방화벽을 설정합니다. Docker의 게시 포트와 UFW의 상호작용도 확인하세요.

내장 S3와 SSO는 HTTP로 구성합니다. HTTPS는 사내 TLS 프록시와 인증서를 별도로 준비해야 하며, S3 TLS 종단이 이미 준비되어 있으면 외부 저장소 연결 방식으로 설정합니다.

DB 복원과 앱 기동

설치 후 상세 절차는 /opt/intellidesk/installer/README.md에서도 확인할 수 있습니다. 다음 명령은 저장소를 clone한 Ubuntu 서버 SSH 터미널에서 실행합니다.

sudo python3 /opt/intellidesk/installer/manage.py infra
sudo python3 /opt/intellidesk/installer/manage.py restore-db --backup /안전한경로/install.dump
cd ~/intellidesk-source
sudo python3 /opt/intellidesk/installer/manage.py build --source "$PWD"
sudo python3 /opt/intellidesk/installer/manage.py check-app
sudo python3 /opt/intellidesk/installer/manage.py start
sudo python3 /opt/intellidesk/installer/manage.py status

restore-db는 신뢰할 수 있는 pg_dump -Fc 백업을 빈 내장 DB에 복원합니다. 기존 DB를 덮어쓰지 않습니다. 외부 DB는 DB 관리자가 준비합니다. 활성 테넌트의 연결정보·암호화된 DB 비밀번호와 도메인도 설치 환경에 맞아야 합니다. 시작 전 검사에서 활성 테넌트가 다른 DB를 가리키면 중단합니다.

server/database/create_tables_tenant.sql은 테넌트 DDL 원본이며 설치 DB 완성본이 아닙니다. 스키마 치환, 기본 시드, public.tenants의 활성 연결정보, 설치 환경 키로 암호화한 DB 비밀번호와 앱 관리자 계정이 별도로 필요합니다. server/database/old/의 SQL은 현재 설치 기준으로 사용하지 않습니다. 이 구성을 별도 환경에서 검증한 뒤 고객 데이터와 기존 서버 정보를 제외한 custom-format 덤프를 준비합니다.

--source는 Windows PC 경로가 아니라 Ubuntu 서버의 Git 저장소 경로입니다. build는 지정 원본 저장소의 HEAD 커밋에서 별도 빌드 입력을 추출합니다. 커밋되지 않은 변경은 포함하지 않습니다. Node.js·npm 설치와 빌드는 컨테이너 내부에서 처리합니다. 모든 활성 테넌트 마이그레이션이 성공해야 서비스 기동을 진행합니다.

앱 슈퍼 관리자 생성

SSO 최초 관리자와 IntelliDesk 앱 슈퍼 관리자는 서로 다른 계정입니다. 앱 이미지와 테넌트 DB가 준비된 뒤 public.tenants.id에 등록된 활성 테넌트 ID를 지정해 앱 계정을 생성합니다.

sudo python3 /opt/intellidesk/installer/manage.py super-admin \
  --tenant acme \
  --user-id admin \
  --email admin@acme.internal \
  --name "Super Admin"

초기 비밀번호는 실행 중 두 번 입력하며 화면에 표시되지 않습니다. 계정은 활성·이메일 인증 완료 상태로 생성되고 SUPER_ADMIN과 ADMIN 권한을 받습니다. 첫 로그인 후 비밀번호 변경이 강제됩니다. 같은 사용자 ID가 이미 있으면 중단하므로 기존 계정을 복구할 때만 --reset-existing을 추가합니다. 같은 이메일을 다른 사용자 ID가 사용 중이면 해당 계정은 변경하지 않습니다.

회원가입 이메일 인증 설정

신규 온프레미스 설치는 Resend API가 없는 사내망을 고려해 회원가입 이메일 인증을 기본적으로 사용하지 않습니다. 이메일과 비밀번호 로그인은 그대로 사용하며 새 가입자는 즉시 활성 상태가 됩니다. 설치 후에는 다음 명령으로 바꿀 수 있습니다.

sudo python3 /opt/intellidesk/installer/manage.py email-verification --disable
sudo python3 /opt/intellidesk/installer/manage.py email-verification --enable

명령은 config/app.env를 갱신하고 서버·작업자 컨테이너를 다시 생성해 즉시 반영합니다. 인증을 끄면 회원가입 인증 메일과 재발송은 Resend를 호출하지 않습니다. 기존 가입 대기 계정을 자동으로 활성화하지 않으므로 관리자가 검토해야 합니다. 비밀번호 찾기 메일은 계속 메일 공급자가 필요하며, 슈퍼 관리자 비밀번호는 super-admin --reset-existing으로 복구할 수 있습니다.

설정 보관과 원본 삭제

/opt/intellidesk/config/에 서비스별 환경 설정을 저장하고 비밀정보 파일은 권한 600으로 제한합니다. 재실행해도 자격증명과 데이터를 자동으로 초기화하지 않습니다. 설정은 셸 스크립트가 아니므로 source하지 않습니다.

원본의 .git, .env*, 인증서·개인키, 테스트와 로컬 DB를 배포본에서 제외합니다. 실제 실행은 독립 Docker 이미지에서 이루어져 원본 폴더 삭제 후에도 실행할 수 있습니다. 다만 이미지와 build/source에는 JavaScript가 남습니다. 암호화나 난독화를 제공하는 기능은 아닙니다.

로그인, 테넌트 접근, 파일 업로드·조회·삭제, 노트북, AI, SSO 기능을 검증한 후 원본 폴더를 직접 삭제하세요. 자동 삭제는 하지 않습니다.

중지와 백업

sudo python3 /opt/intellidesk/installer/manage.py stop

중지해도 Docker 데이터 볼륨은 유지됩니다. 설정 폴더뿐 아니라 PostgreSQL·Redis·SeaweedFS·SSO 볼륨을 백업하고 복원 시험을 수행합니다. down -v와 볼륨 정리는 데이터를 삭제할 수 있습니다. 자동 백업, 업데이트·롤백, 이중화는 이 버전의 범위에 포함되지 않습니다.

설치 도구의 자동 테스트와 Compose 설정 검사는 실행 환경의 전체 검증을 대신하지 않습니다. Ubuntu 검증 서버에서 이미지 빌드·기동과 실제 업무 흐름을 확인한 후 운영에 적용하세요.