Ubuntu / Debian에 설치

Ubuntu 24.04+, Debian 13+ (x86_64). 두 개의 명령, 세 가지 질문.

설치

1. 패키지 다운로드

서버를 호스팅할 머신에서 일반 세션으로 실행합니다:

cd /tmp && wget -N https://uversion.io/downloads/server/uversion-server_latest_amd64.deb

_latest_ URL은 항상 가장 최근에 게시된 버전을 가리킵니다. -N 플래그는 원격 파일이 더 최신일 때만 다시 다운로드하도록 wget에 지시합니다: .deb.1, .deb.2 등의 복사본을 쌓지 않고 업데이트할 때 유용합니다. .deb가 홈 디렉터리에 있을 때 cd /tmp는 외관상의 apt 경고("unsandboxed as root")를 방지합니다.

2. 설치 시작

방금 패키지를 다운로드한 디렉터리에서 명령 하나를 실행합니다:

sudo apt install ./uversion-server_latest_amd64.deb

그러면 설치 프로그램은 아래 세 단계의 순서대로 세 가지 질문을 합니다. 전체 화면의 파란색 대화 상자에 표시됩니다: Tab으로 이동하고 Enter로 확인합니다.

3. 답변: 데이터 디렉터리

기본값: /var/lib/uversion. 버전 관리되는 파일의 내용이 여기에 저장되므로 커지는 디렉터리이며, 따라서 대용량 디스크에 두고 싶은 디렉터리입니다. 모든 경로가 허용되는 것은 아닙니다: 데이터 디렉터리 선택 섹션에 네 가지 규칙이 있으며, 설치 프로그램은 위반한 규칙을 지목하여 거부합니다.

4. 답변: 데이터베이스도 데이터 디렉터리에 둘까요?

기본값: 아니요. 이것은 설치에서 가장 중대한 질문이며, 이 기본값을 그대로 두기 전에 알아야 할 비용이 있습니다.

5. 답변: 활성화 코드

필수입니다. 단, 머신 또는 3단계에서 선택한 디스크에 이미 라이선스가 있는 경우는 예외입니다: 이 경우 설치 프로그램은 전용 메시지로 이를 알리고 질문하지 않습니다. 활성화 코드는 일회용이며, 당신의 코드는 이 디스크가 나온 머신에서 이미 소비되었기 때문입니다.

이 필드는 세 가지 형식을 받습니다. 이는 머신에 인터넷이 없을 때의 탈출구입니다: 짧은 코드 UV-XXXX-XXXX-XXXX, 전체 라이선스 키가 담긴 파일의 절대 경로, 또는 그 전체 키를 직접 붙여 넣은 것 (eyJ로 시작하는 긴 문자열). 첫 번째 형식일 때만 설치 프로그램이 licence.uversion.io에 연결하여 코드를 전체 키로 교환합니다.

6. 끝에 표시되는 내용을 적어 두기

설치는 색상이 있는 상자로 끝납니다: admin 사용자명, 임시 비밀번호, 서버 주소, 인증서 지문. 이것들을 적어 두세요: 이 비밀번호가 담긴 파일은 비밀번호를 변경하는 즉시 삭제됩니다.

그런 다음 첫 로그인을 따라갈 수 있습니다.

설치 프로그램이 받아들일 데이터 디렉터리 선택

규칙은 네 가지입니다. 처음 세 가지는 활성화 코드가 소비되기 전에 검증되므로 거부되어도 손해가 없습니다: 고쳐서 다시 시작하면 됩니다.

• /home 아래도, /root 아래도 아닐 것. 서버는 개인 디렉터리에 대한 접근이 의도적으로 완전히 배제된 시스템 계정으로 실행됩니다: 그곳에서는 결코 읽거나 쓸 수 없으며 시작되지도 않습니다.
• 경로에 공백이 없을 것. 경로는 서비스 설정에 그대로 복사되는데, 거기서는 공백이 두 값을 구분합니다. /media/jean/My Book 같은 이름으로 자동 마운트된 외장 디스크가 바로 여기에 걸립니다.
• 절대 경로일 것, 즉 /로 시작할 것.
• 각 상위 디렉터리가 uversion과 postgres 계정을 통과시킬 것. 이것은 가장 눈에 띄지 않는 함정이며, root로 설치할 때는 보이지 않습니다: 손으로 만들어 닫아 둔 상위 디렉터리(예: Helix 데포에서 물려받은 root:root 0750의 /perforce)는 설치 전체를 통과시킨 뒤 첫 접근에서 서비스를 막습니다. 증상은 status=200/CHDIR로 시작을 거부하는 서비스, 또는 첫 쓰기에서의 "Permission denied"입니다.

이 마지막 사항을 설치 시작 전에 확인하려면, 선택한 위치로 이어지는 전체 디렉터리 체인의 권한을 표시합니다:

namei -l /srv/uversion        # remplacez par le chemin que vous voulez utiliser

각 줄의 마지막 권한 열("기타"의 열)에 x가 있어야 합니다. 하나라도 없으면 설치 프로그램이 문제의 디렉터리와 실행할 정확한 명령(sudo chmod o+x /le/dossier 형식)을 알려 줍니다. 설치 프로그램은 자신이 소유하지 않은 디렉터리를 스스로 변경하는 일이 결코 없습니다: 당신의 트리에 접근을 여는 것은 당신의 결정이지 설치 프로그램의 결정이 아닙니다.

파일이 저장되는 위치

위치는 두 곳이며, 데이터 디렉터리를 바꾸면 그중 하나만 따라옵니다.

데이터 디렉터리 안(질문 1의 그것): 버전 관리되는 파일의 내용 (data/chunks 아래), TLS 인증서와 그 지문(data/tls 아래), 서버 신원 (server-id, last-validated-at), 초기 관리자 비밀번호 (initial-admin-password, 변경하는 즉시 지워짐), PostgreSQL 데이터베이스 (pgdata), 그리고 질문 2에 예라고 답했다면 복구 키트(recovery).

/etc/uversion/ 안, 이곳은 절대 움직이지 않습니다: 구성 파일 config.toml, 라이선스 키의 순수 사본(licence-key), 데이터베이스 비밀번호(db-password).

sudo sed -n 's/^WorkingDirectory=//p' /etc/systemd/system/uversion-server.service.d/10-data-dir.conf

설치 확인

독립된 세 가지 확인을 이 순서로 실행합니다: 서비스가 실행 중이고, 수신 대기하며, 아무것도 보고하지 않았다.

1. 서비스가 실행 중이다

systemctl status uversion-server

예상값: active (running). 다른 값이면 문제 해결로 넘어갑니다.

2. 서버가 8443에서 HTTPS로 수신 대기한다

ss -tlnp | grep 8443

한 줄이 나타나야 합니다. 서비스가 실행 중인데 아무것도 나오지 않는다면 대개 구성에서 TLS가 비활성화된 것입니다: 그러면 서버는 평문 HTTP로 전환되고 8443은 전혀 수신 대기하지 않습니다.

3. 로그에 오류가 없다

sudo journalctl -u uversion-server -n 50

journalctl은 시스템의 로그 리더입니다: 서버가 무엇을 하는지 기록하는 곳이며, 무언가가 시작되지 않을 때 가장 먼저 봐야 할 곳입니다.

인증서 지문 다시 표시

<data-dir>를 위에서 읽은 값으로 바꿔서:

sudo cat <data-dir>/data/tls/fingerprint

초기 관리자 비밀번호 다시 표시

변경되지 않은 한, 아직 디스크에 있습니다:

sudo cat <data-dir>/initial-admin-password

여기서 "No such file or directory"가 나오는 것은 비밀번호가 이미 변경되었다는 뜻입니다: 이는 예상된 동작으로, 그 시점에 파일이 삭제됩니다.

비대화형 및 오프라인 설치

서로 다른 두 가지 필요, 같은 하나의 메커니즘: apt를 실행하기 전에 답변을 미리 채워 두어 어떤 질문도 표시되지 않게 합니다. 이 답변을 저장하는 시스템은 debconf라고 하며, 명령줄에서 다룹니다.

1. 세 답변 미리 채우기

질문마다 한 줄, 대화형 설치의 바로 그 세 가지입니다:

echo 'uversion-server uversion-server/data-dir string /srv/uversion' | sudo debconf-set-selections
echo 'uversion-server uversion-server/db-on-data-dir boolean true'   | sudo debconf-set-selections
echo 'uversion-server uversion-server/licence-key string UV-XXXX-XXXX-XXXX' | sudo debconf-set-selections

2. 대화 상자 없이 설치

답변이 이미 자리 잡았으므로 설치는 더 이상 아무것도 묻지 않습니다:

sudo DEBIAN_FRONTEND=noninteractive apt install -y ./uversion-server_latest_amd64.deb

오프라인 변형: 코드 대신 키 주기

인터넷 접속이 없는 네트워크에서는 활성화 코드를 교환할 수 없습니다: 연락할 상대가 없기 때문입니다. 그럴 때는 연결된 워크스테이션의 계정 영역에서 전체 라이선스 키를 받아 머신에 두고, 위 1단계에서 코드 대신 파일 경로를 줍니다. 이것이 유일한 탈출구이며, 이를 위해 마련되어 있습니다:

echo 'uversion-server uversion-server/licence-key string /root/uversion-licence.key' | sudo debconf-set-selections

파일에는 키 하나만, 한 줄로, 따옴표나 다른 내용 없이 담아야 합니다. 실수로 config.toml 전체를 가리키면 명시적으로 거부됩니다. 파일을 두고 싶지 않다면 세 번째 가능한 형식: 경로 대신 전체 키를 값에 직접 붙여 넣습니다.

위험한 작업 전에 백업하기

복사할 것은 세 가지이며, 각기 다른 방식으로 백업됩니다: 데이터베이스(계정, 리비전, 잠금, 권한), 데이터 디렉터리(파일 내용), 그리고 다른 곳에 있어 사람들이 잊어버리는 구성입니다.

1. 데이터베이스

백업은 postgres 계정으로 하며, 결코 root로 하지 않습니다: PostgreSQL에는 root라는 이름의 "역할"(데이터베이스 계정을 뜻하는 PostgreSQL 용어)이 없으므로, root로 직접 실행한 명령은 실제로는 신원 문제인데도 고장처럼 보이는 메시지로 실패합니다.

데이터베이스에 대한 질문에 아니요(기본값)라고 답했다면, 그것은 시스템 클러스터에 있습니다:

sudo -u postgres pg_dump -Fc uversion > /tmp/uversion.dump

예라고 답했다면, 그것은 별도의 클러스터에 있으며, 명시적으로 지정하지 않으면 엉뚱한 것을 백업하게 됩니다:

pg_lsclusters                                    # repere la ligne "uversion" et sa version
sudo -u postgres pg_dump --cluster <major>/uversion -Fc uversion > /tmp/uversion.dump

2. 데이터 디렉터리

일관된 사본을 위해 서비스를 멈추고:

sudo systemctl stop uversion-server
sudo tar czf /tmp/uversion-data.tar.gz -C <data-dir> .
sudo systemctl start uversion-server

3. 구성

/etc/uversion/은 데이터 디렉터리를 따라가지 않고 데이터베이스에도 없습니다: 라이선스 키, 세션에 서명하는 시크릿, 데이터베이스 비밀번호를 담고 있습니다. 이것이 없으면 새 머신에서의 복원은 새 시크릿으로 다시 시작되므로 팀 전체가 한꺼번에 연결이 끊기고, 라이선스를 다시 요청해야 합니다.

sudo tar czf /tmp/uversion-etc.tar.gz -C /etc uversion

제거

1. 패키지 퍼지

퍼지는 바이너리, 서비스, 구성 응답, /etc/uversion/, 시스템 계정 uversion을 제거합니다. 데이터베이스와 데이터 디렉터리는 의도적으로 보존합니다: 이것들은 당신의 파일이며, 패키지 관리자가 몰래 지우지 않습니다.

sudo systemctl stop uversion-server 2>/dev/null
sudo apt purge -y uversion-server

2. 퍼지가 방금 표시한 순서를 따르기

데이터베이스와 데이터 디렉터리는 여전히 남아 있고, 그것들을 제거하는 명령은 당신의 머신에 따라 다릅니다: 그래서 여기에 적지 않고 계산되어 화면에 표시됩니다.

이 순서가 피하는 두 가지 함정이 있으며, 이것이 가이드에서 복사하지 않고 당신을 위해 계산되는 이유입니다:

• 클러스터를 지정하지 않은 DROP DATABASE는 엉뚱한 데이터베이스 서버를 겨냥합니다. 데이터베이스에 대한 질문에 예라고 답했다면 당신의 것은 전용 클러스터에 있습니다: 기본 명령은 시스템 클러스터를 대상으로 하여 삭제할 것을 찾지 못하고, 완료된 것처럼 믿게 만듭니다.
• 클러스터를 먼저 제거하지 않고 데이터 디렉터리를 rm -rf 하면 시스템에 여전히 선언된 유령 데이터베이스가 남아, 더 이상 존재하지 않는 디렉터리를 요구하며 머신이 부팅될 때마다 실패합니다. 순서가 중요합니다: pg_dropcluster --stop, 그런 다음 디렉터리 삭제.

3. 복구 키트 제거

디스크가 당신의 통제를 벗어나야 할 때(재판매, 임대 반납, 폐기) 수행합니다: 이 디렉터리에는 라이선스 키, JWT 시크릿, 데이터베이스 비밀번호가 들어 있으며, 구조상 퍼지 후에도 남습니다.

sudo rm -rf <data-dir>/recovery

4. 시스템 계정이 사라졌는지 확인

보통 퍼지에 의해 이미 제거됩니다. 사라진 경우 이 명령은 아무 효과가 없습니다:

sudo deluser --system uversion 2>/dev/null || true

5. 아무것도 남지 않았는지 확인

네 가지 확인, 각각 옆에 읽어야 할 내용을 함께 적었습니다:

systemctl status uversion-server         # "not-found" ou "inactive"
ls /etc/uversion 2>&1                    # "No such file"
id uversion                              # "no such user"
sudo -u postgres psql -tAc "SELECT 1 FROM pg_database WHERE datname='uversion';"   # (vide)