서버 운영
공동 작업 서버 운영하기
Oleafly Server가 저장하는 것과 필요한 것, 명령 한 줄로 설치하는 방법, Docker Compose, Coolify, Render, Railway, 일반 Linux 서비스로 실행하는 방법, 그리고 첫 관리자가 되는 방법을 설명합니다.
Oleafly Server는 실시간 공동 작업을 뒷받침하는 공동 작업 서버입니다. 연구실, 학과, 기관이 자체 장비나 자체 클라우드 계정에서 운영합니다. 사람들은 Oleafly에서 서버를 추가하고, GitHub나 대학 로그인처럼 이미 가진 계정으로 로그인합니다. 누군가 서버에서 프로젝트를 공유하면, 추가된 사람들은 편집하는 동안 동기화가 유지되는 전체 사본을 받습니다. 브라우저 접근이 켜져 있으면 웹 브라우저에서 프로젝트를 열 수도 있습니다.
이 가이드는 연구실, 수업, 공저자 그룹을 위해 서버를 운영하는 사람을 위한 것입니다. 터미널을 다룰 줄 알아야 합니다. 일부 설정에서는 구성 파일도 편집해야 합니다. 코드를 작성할 필요는 없습니다.
보안 검토를 위해 서버 보안을 읽어 보세요. 자체 호스팅, 로그인, 기기 키, 서명된 변경, 보안 로그와 접근 로그, 소프트웨어 자재 명세서가 있는 컨테이너 이미지를 다룹니다.
서버가 보관하는 것
섹션 제목: “서버가 보관하는 것”서버는 모든 것을 OLEAFLY_DATA_DIR로 정한 하나의 데이터 폴더에 보관합니다.
- 계정: 각 멤버의 표시 이름, 아바타 주소, 인증된 이메일 주소, 그리고 로그인 제공자에서의 사용자 ID와 로그인 이름. 서버는 비밀번호를 보거나 저장하지 않습니다.
- 기기: 로그인한 각 컴퓨터의 이름, 운영 체제, 공개 키, 마지막으로 접속한 시각. 로그인 토큰은 해시로만 저장됩니다.
- 보안 로그: 로그인과 거부된 로그인, 추가되거나 로그아웃된 기기, 멤버, 역할, 설정의 변경, 공유, 보관, 복원된 프로젝트, 프로젝트를 열 수 있는 사람의 변경, 게스트 초대. 각 항목에는 시각과 IP 주소가 있습니다.
- 관리자가 Oleafly에서 바꾸는 서버 설정.
- 프로젝트 접근 로그: 소유자가 켠 프로젝트에 한해, 누가 프로젝트를 열고, 참여하고, 사본을 내려받았는지를 기기 이름과 시각과 함께 기록합니다. 프로젝트 소유자만 읽을 수 있습니다.
- 게스트 초대: 초대한 이메일 주소, 프로젝트, 역할, 보낸 사람.
- 공유 프로젝트: 모든 파일과 변경의 전체 기록, 그리고 프로젝트에 속한 댓글, 제안, 채팅, 버전 이름.
- 컴파일된 PDF: 공유 프로젝트마다 소유자나 편집자의 앱이 컴파일에 성공한 뒤 보낸 최신 PDF와 그 SyncTeX 파일, 그리고 누가 언제 컴파일했는지.
보안 로그와 접근 로그의 항목, 그리고 응답했거나 만료된 게스트 초대는 OLEAFLY_SECURITY_LOG_DAYS일이 지나면 삭제되며 기본값은 365일입니다. 교체된 그림의 이전 사본처럼 프로젝트가 더 이상 쓰지 않는 파일은 프로젝트가 마지막으로 사용한 뒤 30일이 지나면 삭제됩니다. 새로 컴파일된 PDF는 이전 PDF를 대체합니다. 소유자가 프로젝트 공유를 중지하면 서버는 OLEAFLY_ARCHIVE_DAYS일 동안(기본값 30일) 읽기 전용으로 보관하다가 삭제합니다. 그 기간에는 소유자와 프로젝트의 관리자만 내려받을 수 있습니다.
프로젝트를 읽을 수 있는 사람
섹션 제목: “프로젝트를 읽을 수 있는 사람”서버에서 프로젝트는 암호화되지 않습니다. 데이터 폴더, 장비의 디스크, 백업을 읽을 수 있는 사람은 거기에 저장된 모든 프로젝트를 읽을 수 있습니다. 장비를 운영하는 사람과 이를 호스팅하는 회사도 여기에 포함됩니다.
Oleafly 안에서의 규칙은 더 엄격합니다. 프로젝트 소유자가 추가하지 않은 사람은 관리자를 포함해 어떤 서버 역할도 프로젝트를 열 수 없습니다. 서버를 운영하는 사람에게 프로젝트를 숨겨야 한다면 그 프로젝트를 위한 별도 서버를 운영하세요.
모든 멤버의 컴퓨터에도 공유받은 각 프로젝트의 전체 사본이 있습니다. 멤버에게 macOS의 FileVault, Windows의 BitLocker, Linux의 LUKS 같은 디스크 암호화를 켜도록 요청하세요.
필요한 것
섹션 제목: “필요한 것”- 계속 켜져 있는 장비. 어떤 Linux 장비든 되며, Render나 Railway 같은 호스팅 서비스 계정도 됩니다. 시작할 때는 작은 가상 머신이면 충분합니다. 프로젝트가 늘어나면 메모리와 디스크를 지켜보세요. 서버는 x86-64와 ARM에서 실행됩니다.
- 서버의 도메인 이름(예:
collab.example.org)과 장비를 가리키는 DNS 레코드. 도메인이 없으면 Render와 Railway가 주소를 제공합니다. 장비에 공개 주소가 없다면 공개 주소가 없을 때를 읽어 보세요. - 사람들이 로그인할 방법: GitHub OAuth 앱이나 소속 기관의 로그인 같은 로그인 제공자 하나 이상. 제공자가 없으면 서버가 시작되지 않습니다. 서버가 메일을 보낼 수 있는 이메일 계정은 선택 사항입니다. 있으면 관리자가 이메일로 받은 링크로 로그인하게 할 수도 있습니다. 로그인과 접근을 읽어 보세요.
각 릴리스는 컨테이너 이미지 ghcr.io/oleafly/oleafly-server로 배포됩니다. 설치 프로그램과 Compose 파일은 Oleafly Server 릴리스 페이지 (새 탭에서 열림)에 있습니다. 단일 Linux 프로그램으로 된 서버는 Oleafly 릴리스 페이지 (새 탭에서 열림)에 있습니다.
실행 방법 고르기
섹션 제목: “실행 방법 고르기”| 방법 | 사용하는 경우 |
|---|---|
| 명령 한 줄 | 직접 관리하는 Linux 장비. 설치 프로그램이 Docker, Caddy, HTTPS를 설정하고 몇 가지를 묻습니다. 잘 모르겠다면 여기서 시작하세요. |
| 직접 하는 Docker Compose | 각 파일을 직접 배치하고 편집하고 싶을 때. |
| Coolify | 이미 Coolify 서버를 운영하고 있을 때. |
| Render 또는 Railway | 장비를 관리하는 대신 호스팅 서비스에 비용을 내고 싶을 때. |
| Docker 없는 Linux | Docker를 쓸 수 없는 대학 가상 머신. |
서버는 환경 변수에서 설정을 읽습니다. 모든 설정은 저장소, 백업, 한도에 나와 있습니다.
명령 한 줄로 설치하기
섹션 제목: “명령 한 줄로 설치하기”직접 관리하는 Linux 장비에서는 설치 프로그램이 모든 것을 설정하고 꼭 필요한 것만 묻습니다.
실행하기 전에 다음을 확인하세요.
- 장비가 x86-64나 ARM의 Linux(예: Ubuntu 24.04, Debian 13)이고
sudo를 쓸 수 있습니다. - 장비의 다른 어떤 것도 80번과 443번 포트를 쓰지 않습니다. 장비 앞의 방화벽에서 TCP 80, 443 포트와 UDP 443 포트를 여세요.
- 도메인의 DNS 레코드가 장비를 가리킵니다. 아직 가리키지 않아도 설치는 끝나며, Caddy는 레코드가 준비될 때까지 인증서 발급을 계속 시도합니다.
- 로그인 제공자 하나 이상의 정보가 있습니다. 예를 들어 GitHub OAuth 앱의 클라이언트 ID와 시크릿입니다. GitHub의 콜백 주소는
https://에 도메인을 붙이고/auth/callback/github를 이어 붙인 것입니다.
그런 다음 실행합니다.
curl -fsSL https://oleafly.com/server/install.sh | sudo sh설치 프로그램은 다음을 수행합니다.
- 장비를 확인하고 80번과 443번 포트가 비어 있는지 확인합니다.
- Docker가 있는지 확인합니다. 없으면 설치 프로그램이 Docker의 자체 스크립트로 설치해도 되는지 묻습니다.
- 최신 릴리스의 파일을 Oleafly Server 릴리스 (새 탭에서 열림)에서 내려받고 각 파일을 릴리스의
SHA256SUMS와 대조합니다. 일치하지 않는 파일이 있으면 아무것도 바꾸지 않고 멈춥니다. - 도메인, 서버 이름, 로그인 방법을 묻습니다. 이메일 설정과 S3 버킷에 파일 보관도 제안하며, 둘 다 선택 사항입니다.
- 요약을 보여 주고 무엇이든 바꾸기 전에 묻습니다. 그런 다음 파일을
/opt/oleafly-server에 쓰고, 설정은 root만 읽을 수 있는.env에 넣습니다. - 앞단에 Caddy를 둔 서버를 시작하고, 도메인이 HTTPS로 응답할 때까지 기다린 뒤, 주소와 설정 코드를 출력합니다.
그런 다음 첫 관리자가 되세요.
설치 프로그램은 언제든 다시 실행할 수 있습니다. /opt/oleafly-server에서 서버를 찾으면 .env는 그대로 두고, 나머지 파일을 다시 배치하고, 서버를 다시 시작합니다. 대부분의 깨진 설정은 이것으로 복구됩니다.
데이터는 Docker 볼륨 oleafly-server_oleafly-data에 있습니다. /opt/oleafly-server가 아닌 곳에 설치하려면 OLEAFLY_DIR을 설정하세요. 예를 들어 curl -fsSL https://oleafly.com/server/install.sh | sudo OLEAFLY_DIR=/srv/oleafly sh이며, 아래 명령에서는 그 폴더를 쓰세요.
설치 프로그램 먼저 읽기
섹션 제목: “설치 프로그램 먼저 읽기”기관이 스크립트를 셸로 바로 파이프하는 것을 허용하지 않으면, install.sh와 SHA256SUMS를 최신 릴리스 (새 탭에서 열림)에서 한 폴더에 내려받으세요. 스크립트를 확인하고 읽은 다음 실행합니다.
sha256sum --check --ignore-missing SHA256SUMSsudo sh install.sh질문 없이 설치하기
섹션 제목: “질문 없이 설치하기”스크립트나 프로비저닝 도구에서는 --yes를 붙이고 답을 환경 변수로 전달하세요. OLEAFLY_INSTALL_DOCKER=yes를 쓰면 Docker가 없을 때 설치 프로그램이 Docker를 추가할 수 있습니다.
curl -fsSL https://oleafly.com/server/install.sh | sudo \ OLEAFLY_DOMAIN=collab.example.org \ OLEAFLY_SERVER_NAME='Smith Lab' \ OLEAFLY_GITHUB_CLIENT_ID=Ov23liExampleClientId \ OLEAFLY_GITHUB_CLIENT_SECRET=example-client-secret \ OLEAFLY_INSTALL_DOCKER=yes \ sh -s -- --yes설치 프로그램은 환경에서 찾은 설정을 --yes가 있든 없든 묻지 않고 씁니다. sudo sh /opt/oleafly-server/install.sh --help를 실행하면 OpenID Connect, 이메일, S3를 포함한 모든 설정이 나옵니다. 명령줄에 입력한 값은 셸 기록에 남을 수 있으므로, 프로비저닝 도구는 시크릿을 자체 시크릿 저장소에서 전달해야 합니다.
상태, 업데이트, 제거
섹션 제목: “상태, 업데이트, 제거”-
상태:
sudo sh /opt/oleafly-server/install.sh status는 서버가 실행 중인지, 도메인이 유효한 인증서로 HTTPS 응답을 하는지 보여 줍니다. -
업데이트: 먼저 업데이트에서 설명하는 대로 백업하세요. 그런 다음 아래 명령을 실행합니다. 최신 릴리스의 파일과 이미지를 내려받고,
.env를 유지하고, 서버를 다시 시작하고, 응답할 때까지 기다립니다. 연결되어 있던 사람들은 저절로 다시 연결됩니다. 설치 프로그램은 서버를 이전 릴리스로 되돌리지 않습니다.터미널 창 curl -fsSL https://oleafly.com/server/install.sh | sudo sh -s -- update -
제거:
sudo sh /opt/oleafly-server/install.sh uninstall은 컨테이너를 멈추고 제거합니다. 묻는 단계에서delete를 입력하지 않으면 데이터와.env는 남습니다. 삭제하면 서버의 모든 공유 프로젝트, 모든 계정, 보안 로그가 사라집니다. 사람들은 자기 컴퓨터에 프로젝트 사본을 그대로 가지고 있습니다.
설치 프로그램이 해결할 수 없는 문제로 멈추면 출력된 내용과 함께 신고 (새 탭에서 열림)하세요.
직접 하는 Docker Compose
섹션 제목: “직접 하는 Docker Compose”이 설정은 컨테이너 두 개를 실행합니다. oleafly-server가 서버이며 다른 컨테이너만 접근할 수 있습니다. caddy는 Let’s Encrypt에서 인증서를 받고, 80번과 443번 포트에서 HTTPS를 제공하고, 실시간 연결을 포함한 요청을 서버로 전달합니다.
-
Docker의 안내 (새 탭에서 열림)에 따라 Docker Engine과 Compose 플러그인을 설치합니다.
-
도메인의 DNS 레코드가 장비를 가리키게 합니다. 장비 앞의 방화벽에서 TCP 80, 443 포트와 UDP 443 포트를 엽니다. Caddy는 인증서를 받으려면 80번 포트가 필요합니다.
-
서버용 폴더를 만들고, 최신 릴리스의 파일을 그 안에 내려받아 확인한 다음, 설정 파일을 만듭니다.
터미널 창 sudo mkdir -p /opt/oleafly-server && cd /opt/oleafly-serverbase=https://github.com/Oleafly/oleafly-server/releases/latest/downloadfor f in docker-compose.yml Caddyfile env.example litestream.yml SHA256SUMS; do sudo curl -fsSLO "$base/$f"; donesha256sum --check --ignore-missing SHA256SUMSsudo install -m 600 env.example .env -
sudoedit .env로.env를 편집합니다.OLEAFLY_DOMAIN은https://없이 도메인으로 설정하고,OLEAFLY_SERVER_NAME을 설정하고, 로그인 제공자를 하나 이상 채웁니다. 쓰지 않는 제공자 줄은 비워 둡니다. 값에$나#이 들어 있으면 작은따옴표로 감쌉니다. -
시작합니다. 처음 시작할 때 릴리스 버전의 서버 이미지
ghcr.io/oleafly/oleafly-server를 내려받습니다.터미널 창 sudo docker compose up -d -
응답하는지 확인합니다.
200이 출력됩니다.터미널 창 curl -sS -o /dev/null -w '%{http_code}\n' https://collab.example.org/healthz -
첫 관리자가 되세요. 설정 코드는 로그에 있습니다.
터미널 창 sudo docker compose logs oleafly-server | grep 'Setup code'
데이터는 Docker 볼륨 oleafly-server_oleafly-data에 있습니다. Caddy는 인증서를 oleafly-server_caddy-data에 보관합니다.
Docker는 ufw 같은 호스트 방화벽이 켜져 있어도 80번과 443번 포트를 직접 엽니다. Caddy에 필요한 동작입니다. oleafly-server 서비스에 ports: 항목을 추가하지 마세요. 장비 자체에서 서버에 접근해야 한다면 127.0.0.1:8080:8080으로 게시해서 네트워크에는 노출되지 않게 하세요.
Caddyfile을 바꿨다면 sudo docker compose up -d --force-recreate caddy를 실행하세요. 나중에 업데이트할 때는 같은 방법으로 새 릴리스의 파일을 내려받고 sudo docker compose up -d를 다시 실행하세요.
.env에 시크릿 두지 않기
섹션 제목: “.env에 시크릿 두지 않기”시크릿을 담을 수 있는 설정은 일곱 가지입니다. OLEAFLY_SETUP_CODE, OLEAFLY_GITHUB_CLIENT_SECRET, OLEAFLY_OIDC_<NAME>_CLIENT_SECRET, OLEAFLY_SMTP_URL, OLEAFLY_BLOB_STORE, OLEAFLY_S3_ACCESS_KEY_ID, OLEAFLY_S3_SECRET_ACCESS_KEY입니다. 각각 값을 담은 파일의 이름을 지정하는 _FILE 버전도 있습니다. 둘 중 하나만 설정하고 둘 다 설정하지는 마세요.
예를 들어 GitHub 클라이언트 시크릿을 Docker 시크릿으로 전달하려면, docker-compose.yml 옆의 secrets/github_client_secret에 저장하고, 서버의 사용자(ID 10001)가 읽을 수 있게 하고, .env에서 OLEAFLY_GITHUB_CLIENT_SECRET 줄을 삭제하세요.
sudo chown 10001:10001 secrets/github_client_secretsudo chmod 400 secrets/github_client_secret그런 다음 docker-compose.yml 옆에 docker-compose.override.yml을 만드세요. Compose가 자동으로 읽으며, 설치 프로그램은 다른 파일을 업데이트할 때 이 파일을 건드리지 않습니다.
services: oleafly-server: environment: OLEAFLY_GITHUB_CLIENT_SECRET_FILE: /run/secrets/github_client_secret secrets: - github_client_secret
secrets: github_client_secret: file: ./secrets/github_client_secretsudo docker compose up -d를 다시 실행하세요.
Coolify
섹션 제목: “Coolify”Coolify는 서버 앞에 자체 프록시를 두고 인증서를 받으므로 이 설정에는 Caddy가 없습니다. Coolify는 Oleafly 저장소에서 서버를 빌드할 수도 있고, 빌드를 건너뛰는 게시된 이미지를 실행할 수도 있습니다.
시작하기 전에 collab.example.org 같은 도메인의 DNS 레코드를 Coolify 서버로 지정하세요. 그런 다음 GitHub에서 설명하는 대로 GitHub OAuth 앱을 만들고 콜백 주소는 https://collab.example.org/auth/callback/github로 하세요. 클라이언트 ID와 시크릿을 가까이 두세요.
저장소에서 빌드하기
섹션 제목: “저장소에서 빌드하기”- Coolify 프로젝트에서 + New, Public Repository를 차례로 선택하고
https://github.com/Oleafly/Oleafly를 입력합니다. 브랜치는main으로 둡니다. - Build Pack을 Docker Compose로, Base Directory를
/로, Docker Compose Location을/deploy/server/docker-compose.coolify.yml로 설정한 다음 Continue를 선택합니다. - Advanced › Build에서 Build arguments를 Managed manually in Dockerfile로 설정합니다. 서버 이미지에는 빌드 인수가 필요하지 않습니다. 자동으로 두면 Coolify가 시크릿을 포함한 모든 변수를 이미지의 빌드 기록에 씁니다.
- General에서
oleafly-server의 도메인을https://collab.example.org:8080으로 설정하고 저장합니다.:8080은 서버가 듣는 포트를 Coolify의 프록시에 알려 줍니다. 사람들은 여전히 일반 HTTPS 포트로 접속하며, Coolify가OLEAFLY_PUBLIC_URL을https://collab.example.org로 설정해 줍니다. - Environment Variables에서 Coolify가 필수로 표시한
OLEAFLY_SERVER_NAME을 채운 다음OLEAFLY_GITHUB_CLIENT_ID와OLEAFLY_GITHUB_CLIENT_SECRET을 채웁니다. 쓰지 않는 변수는 비워 둡니다. - Deploy를 선택합니다. 첫 빌드는 서버를 컴파일하므로 몇 분이 걸립니다. 끝나면 Coolify가 리소스를 실행 중이며 정상으로 표시합니다.
- 브라우저에서
https://collab.example.org/healthz를 엽니다.{"status":"ok"}가 표시됩니다. - Logs를 열고
oleafly-server컨테이너를 선택한 다음,Setup code:로 시작하는 가장 최근 줄에서 코드를 복사합니다. - 그 코드로 첫 관리자가 되세요.
서버가 시작되지 않으면 로그에 쓸 수 없는 설정이 나옵니다. OLEAFLY_PUBLIC_URL이 설정되지 않았다고 나오면 4단계가 빠진 것입니다. http://로 시작하는 도메인은 서버가 HTTPS를 필요로 하므로 거부됩니다.
DNS 레코드가 Cloudflare의 프록시를 거치거나 터널이 Coolify의 프록시로 이어져서 Coolify 앞에 Cloudflare가 있다면 OLEAFLY_PROXY_HOPS를 2로 설정하세요. 그러지 않으면 보안 로그에 모든 사람의 주소가 프록시의 주소로 나타나고, 모두가 하나의 로그인 제한을 공유합니다.
Coolify 파일에는 GitHub와 UNIVERSITY라는 OpenID Connect 제공자 하나를 위한 자리가 있습니다. OLEAFLY_OIDC_UNIVERSITY_LABEL을 GitLab처럼 사람들에게 보일 텍스트로 설정하세요. 콜백 주소는 /auth/callback/university로 끝납니다. 제공자를 더 쓰려면 파일을 직접 복사해 둔 포크에서 배포하세요.
데이터는 이름이 oleafly-data로 끝나는 Docker 볼륨에 있습니다. docker volume ls --filter name=oleafly-data로 찾을 수 있습니다. 이미지에는 셸이 없어서 Coolify의 Terminal로 서버 컨테이너에서 셸을 열 수 없습니다. 로그와 상태 확인은 평소처럼 동작합니다.
게시된 이미지 배포하기
섹션 제목: “게시된 이미지 배포하기”게시된 이미지를 실행하면 빌드를 건너뛰므로 작은 Coolify 서버에 알맞습니다. 위 단계를 따르되 두 가지를 바꾸세요. 2단계에서 Docker Compose Location을 /deploy/server/docker-compose.coolify-image.yml로 설정하세요. 3단계는 빌드가 없으므로 건너뜁니다. 이 파일은 하나의 릴리스 시리즈를 따르므로 Redeploy할 때마다 그 시리즈의 최신 릴리스를 받아 옵니다.
Render
섹션 제목: “Render”Deploy to Render (새 탭에서 열림)는 Oleafly 저장소의 Blueprint를 읽습니다. 게시된 이미지로 웹 서비스 하나를 만들고 데이터 폴더용 1 GB 디스크를 붙입니다. Render는 유료 인스턴스 유형에만 디스크를 연결하므로, 서비스는 Render의 오리건 리전에서 가장 작은 유료 유형으로 시작합니다. 다른 리전을 쓰려면 render.yaml에 region을 설정한 포크에서 배포하세요.
- 링크를 열고 Render에 로그인합니다.
- Render가
OLEAFLY_SERVER_NAME과 GitHub 클라이언트 ID와 시크릿을 묻습니다. 이름을 채우고 GitHub 필드는 지금은 비워 둡니다. 콜백 주소는 아직 알 수 없는 서비스 주소에 따라 정해지기 때문입니다. - Deploy Blueprint를 선택합니다. 서비스가 실행되면 서비스 페이지에
https://oleafly-server.onrender.com같은 주소가 표시됩니다. Blueprint는OLEAFLY_PUBLIC_URL을 그 주소로 설정합니다. - GitHub에서 설명하는 대로 GitHub OAuth 앱을 만들되, 콜백 주소는 그 주소 뒤에
/auth/callback/github를 붙인 것으로 합니다. 클라이언트 ID와 시크릿을 서비스의 Environment에 추가합니다. Render가 그 값으로 서버를 다시 시작합니다. - 서비스의 Logs에서 가장 최근의
Setup code:줄을 찾아 첫 관리자가 되세요.
서비스에 자신의 도메인을 지정했다면 Environment에서 OLEAFLY_PUBLIC_URL을 그 도메인으로 설정하고 GitHub의 콜백 주소도 그에 맞게 바꾸세요.
디스크 때문에 Render는 새 서버를 시작하기 전에 실행 중인 서버를 멈추므로, 배포할 때마다 몇 초 동안 서버를 쓸 수 없습니다. Oleafly는 저절로 다시 연결됩니다.
Railway
섹션 제목: “Railway”Railway는 데이터 폴더용 볼륨과 함께 게시된 이미지를 실행합니다.
-
Railway 프로젝트에서 + New, Docker Image를 차례로 선택하고
ghcr.io/oleafly/oleafly-server:latest를 입력합니다. 업그레이드 시점을 직접 정하려면 대신 릴리스 페이지 (새 탭에서 열림)에서 릴리스 고유의 태그를 쓰세요. Railway가 첫 배포를 바로 시작할 수 있습니다. 이 배포는OLEAFLY_PUBLIC_URL is not set이라는 오류로 멈추는데, 이 시점에서는 예상된 동작입니다. -
서비스를 엽니다. Settings › Networking에서 Generate Domain을 선택하고 포트
8080을 입력합니다. Railway가oleafly-server-production.up.railway.app같은 주소를 보여 줍니다. -
Settings › Deploy에서 Healthcheck Path를
/readyz로 설정합니다. -
프로젝트 캔버스를 오른쪽 클릭해 볼륨을 추가하고, 서버의 서비스에 연결하고, 마운트 경로를
/data로 설정합니다. -
Variables에서 Raw Editor를 열고 이 줄들을 자신의 서버 이름으로 붙여 넣습니다. GitHub 값은 GitHub를 따르세요. 콜백 주소는 2단계의 주소 앞에
https://를, 뒤에/auth/callback/github를 붙인 것입니다.OLEAFLY_PUBLIC_URL=https://${{RAILWAY_PUBLIC_DOMAIN}}OLEAFLY_BIND=0.0.0.0:8080OLEAFLY_DATA_DIR=/dataOLEAFLY_BEHIND_PROXY=trueOLEAFLY_SERVER_NAME=Smith LabOLEAFLY_GITHUB_CLIENT_ID=Ov23liExampleClientIdOLEAFLY_GITHUB_CLIENT_SECRET=example-client-secretPORT=8080RAILWAY_RUN_UID=0Railway는 볼륨을 root로 마운트합니다.
RAILWAY_RUN_UID=0은 서버가 볼륨에 쓸 수 있도록 root로 실행합니다. -
변경 사항을 배포합니다. 서비스의 Deploy Logs에서 가장 최근의
Setup code:줄을 찾아 첫 관리자가 되세요.
Docker 없는 Linux
섹션 제목: “Docker 없는 Linux”Docker가 없는 장비에서는 서버가 systemd 아래에서 단일 프로그램으로 실행되고, 앞단에 HTTPS용 Caddy를 둡니다.
서버 내려받기
섹션 제목: “서버 내려받기”릴리스 페이지 (새 탭에서 열림)의 서버 릴리스마다 x86-64와 ARM용으로 미리 빌드된 프로그램과, 확인에 쓰는 SHA256SUMS 파일이 있습니다. 이 프로그램은 다른 것을 설치하지 않아도 실행됩니다.
장비에 맞는 아카이브(이름이 x86_64-unknown-linux-musl.tar.gz 또는 aarch64-unknown-linux-musl.tar.gz로 끝남)와 SHA256SUMS를 한 폴더에 내려받으세요. 그런 다음 확인하고 설치합니다. ARM 장비에서는 x86_64 대신 aarch64를 쓰세요.
sha256sum --check --ignore-missing SHA256SUMStar -xzf oleafly-server-*-x86_64-unknown-linux-musl.tar.gzsudo install -m 0755 oleafly-server-*-x86_64-unknown-linux-musl/oleafly-server /usr/local/bin/oleafly-serveroleafly-server --versionGitHub CLI가 설치되어 있다면 gh attestation verify oleafly-server-*-x86_64-unknown-linux-musl.tar.gz --repo Oleafly/Oleafly로 GitHub가 Oleafly 저장소에서 이 아카이브를 빌드했는지도 확인할 수 있습니다. 아카이브에는 systemd 유닛 oleafly-server.service가 들어 있습니다.
프로그램을 직접 빌드하려면 Docker가 있는 아무 컴퓨터에서 Oleafly 저장소의 클론에서 다음을 실행하세요. ARM 서버에는 --platform linux/arm64를 쓰세요.
docker buildx build --platform linux/amd64 --target binary --output type=local,dest=dist -f crates/oleafly-server/Dockerfile .이 명령은 dist/oleafly-server를 만듭니다. 서버의 /usr/local/bin/oleafly-server로 복사하고 실행 가능하게 만드세요.
systemd로 실행하기
섹션 제목: “systemd로 실행하기”-
설정 파일을 만듭니다. root만 읽을 수 있습니다.
터미널 창 sudo install -d -m 0755 /etc/oleafly-serversudo install -m 0600 /dev/null /etc/oleafly-server/oleafly-server.envsudoedit /etc/oleafly-server/oleafly-server.env한 줄에 설정 하나씩 넣습니다.
OLEAFLY_BIND=127.0.0.1:8080은 서버를 네트워크에 노출하지 않아 Caddy만 접근할 수 있게 합니다. 유닛이OLEAFLY_DATA_DIR을 설정하므로 직접 설정하지 마세요.OLEAFLY_PUBLIC_URL=https://collab.example.orgOLEAFLY_BIND=127.0.0.1:8080OLEAFLY_BEHIND_PROXY=trueOLEAFLY_SERVER_NAME=Smith LabOLEAFLY_GITHUB_CLIENT_ID=Ov23liExampleClientIdOLEAFLY_GITHUB_CLIENT_SECRET=example-client-secret -
압축을 푼 아카이브나 저장소 클론의
deploy/server에서 유닛을 설치하고 시작합니다. 그런 다음 설정 코드를 찾습니다.터미널 창 sudo install -m 0644 oleafly-server.service /etc/systemd/system/oleafly-server.servicesudo systemctl daemon-reloadsudo systemctl enable --now oleafly-serversudo journalctl -u oleafly-server | grep 'Setup code'
유닛은 systemd가 만든 사용자로 서버를 실행하며, 시스템의 나머지 부분은 읽기 전용으로만 보입니다. 서버가 쓸 수 있는 곳은 데이터를 보관하는 /var/lib/oleafly-server뿐입니다. 디스크에서 그 폴더는 /var/lib/private/oleafly-server입니다.
클라이언트 시크릿을 설정 파일에 두지 않으려면 systemd 자격 증명을 쓰세요. 시크릿을 모드 600으로 /etc/oleafly-server/github-client-secret에 저장하고, 설정 파일에서 OLEAFLY_GITHUB_CLIENT_SECRET 줄을 삭제하고, sudo systemctl edit oleafly-server를 실행해 다음을 추가하세요.
[Service]LoadCredential=github-client-secret:/etc/oleafly-server/github-client-secretEnvironment=OLEAFLY_GITHUB_CLIENT_SECRET_FILE=%d/github-client-secret그런 다음 sudo systemctl restart oleafly-server를 실행하세요.
앞단에 HTTPS 두기
섹션 제목: “앞단에 HTTPS 두기”배포판별 안내 (새 탭에서 열림)에 따라 Caddy를 설치하세요. /etc/caddy/Caddyfile을 이 줄들로 바꾸고 sudo systemctl reload caddy를 실행하세요. Caddy가 인증서를 받고 실시간 연결을 그대로 통과시킵니다.
collab.example.org { reverse_proxy 127.0.0.1:8080}nginx나 Apache, 또는 대학이 이미 운영하는 웹 서버를 쓰려면 리버스 프록시 뒤에서를 읽어 보세요.
공개 주소가 없을 때
섹션 제목: “공개 주소가 없을 때”장비에 공개 주소가 없다면, 예를 들어 대학 방화벽 뒤에 있는 연구실 컴퓨터라면 Cloudflare Tunnel로 접근할 수 있게 만들 수 있습니다. 도메인을 등록한 Cloudflare 계정이 필요합니다. Cloudflare가 호스트 이름의 HTTPS를 처리하므로, 요청은 내 장비에 도달하기 전에 Cloudflare 네트워크에서 복호화됩니다. 서버로 가는 트래픽을 읽을 수 있는 주체에 Cloudflare도 포함하세요.
-
.env를 편집하는 단계까지 직접 하는 Docker Compose의 단계를 따릅니다.OLEAFLY_DOMAIN은collab.example.org같이 쓸 호스트 이름으로 설정합니다. 명령 한 줄 설치 프로그램은 Caddy를 시작하므로 여기에는 맞지 않습니다. -
서버만 시작합니다. 여기서는 Caddy가 필요 없습니다.
터미널 창 sudo docker compose up -d oleafly-server -
Cloudflare 대시보드에서 Networking › Tunnels로 가서 Create Tunnel을 선택하고, 이름을 붙이고, Create Tunnel을 다시 선택합니다. 표시되는 설치 명령에서 토큰을 복사합니다.
-
서버 옆에서 터널을 시작합니다.
read명령은 토큰을 붙여 넣을 때까지 기다리며 토큰을 화면에 표시하지 않습니다.터미널 창 read -rs TUNNEL_TOKEN && export TUNNEL_TOKENsudo --preserve-env=TUNNEL_TOKEN docker run -d --name oleafly-tunnel --restart unless-stopped --network oleafly-server_default -e TUNNEL_TOKEN cloudflare/cloudflared:2026.10.0 tunnel --no-autoupdate run -
대시보드로 돌아와 터널을 엽니다. Routes에서 Add route, Published application을 차례로 선택합니다. Hostname에 서브도메인을 입력하고 도메인을 고릅니다. Service URL을
http://oleafly-server:8080으로 설정하고 Add route를 선택합니다. -
https://collab.example.org/healthz에서 응답하는지 확인한 다음 첫 관리자가 되세요.
Docker가 없는 장비에서는 Cloudflare의 패키지 저장소 (새 탭에서 열림)에서 cloudflared를 설치하고, sudo cloudflared service install에 이어 토큰을 지정해 실행하고, Service URL을 http://127.0.0.1:8080으로 설정하세요.
Cloudflare는 실시간 연결을 그대로 통과시키고 방문자의 주소를 X-Forwarded-For의 마지막에 넣으므로 OLEAFLY_BEHIND_PROXY=true를 유지하세요. 터널이 서버로 바로 이어지지 않고 Coolify의 프록시 같은 다른 프록시로 이어진다면 OLEAFLY_PROXY_HOPS=2도 설정하세요. Cloudflare는 Free와 Pro 플랜에서 100 MB보다 큰 요청을 거부하므로, OLEAFLY_MAX_PROJECT_MB를 100 이하로 설정하세요. 그러지 않으면 큰 프로젝트의 업로드가 실패합니다. Oleafly는 Cloudflare Access의 로그인 페이지를 통과할 수 없으므로 서버 앞에 Cloudflare Access를 두지 마세요.
나중에 서버를 업데이트할 때는 새 릴리스의 파일을 내려받고 Caddy가 시작되지 않도록 서비스 이름을 지정하세요. sudo docker compose up -d oleafly-server입니다.
첫 관리자 되기
섹션 제목: “첫 관리자 되기”새 서버에는 관리자가 없습니다. 누군가 설정을 마칠 때까지 서버는 시작할 때마다 일회용 설정 코드를 새로 만들어 로그에 씁니다.
- 로그에서
Setup code:로 시작하는 가장 최근 줄을 찾습니다.- 명령 한 줄 설치: 설치 프로그램이 끝날 때 출력합니다. 다시 보려면
cd /opt/oleafly-server && sudo docker compose logs oleafly-server | grep 'Setup code'를 실행하세요 - 직접 하는 Docker Compose: 서버 폴더에서
sudo docker compose logs oleafly-server | grep 'Setup code' - Coolify:
oleafly-server서비스의 로그 - systemd:
sudo journalctl -u oleafly-server | grep 'Setup code'
- 명령 한 줄 설치: 설치 프로그램이 끝날 때 출력합니다. 다시 보려면
- Oleafly에서 설정 → 공동 작업을 열고 서버 추가를 선택한 다음 서버 주소를 입력합니다. Oleafly가 서버에 설정이 필요한 것을 알아보고 설정 코드를 묻습니다.
- 코드를 입력하고 설정해 둔 제공자 중 아무것으로 로그인합니다. 내가 서버의 관리자가 되고 코드는 더 이상 쓸 수 없게 됩니다.
코드를 사용하기 전에 코드를 가진 사람은 누구나 자신을 관리자로 만들 수 있으므로, 코드는 Oleafly에만 붙여 넣으세요.
OLEAFLY_SETUP_CODE로 코드를 직접 정할 수도 있습니다. 문자나 숫자 12자 이상이며 원하면 대시나 공백을 넣을 수 있습니다. 그러면 서버는 코드를 출력하지 않습니다. 로그에는 Setup code: set by OLEAFLY_SETUP_CODE라고만 나오며, 정해 둔 값을 입력하면 됩니다. 설정이 끝나면 설정에서 제거하세요.
다음으로 사람들을 들이세요. 방법은 로그인과 접근에서 설명합니다.
서버 확인하기
섹션 제목: “서버 확인하기”- 명령 한 줄 설치에서는
sudo sh /opt/oleafly-server/install.sh status가 컨테이너와 HTTPS를 한 번에 확인합니다. https://collab.example.org/healthz는 서버 프로세스가 실행되는 동안200으로 응답합니다./readyz는 서버가 데이터베이스와 데이터 폴더에 쓸 수 있을 때만200으로 응답합니다. 디스크가 가득 찬 경우처럼 쓸 수 없으면503으로 응답하고 실패한 대상인database또는storage를 알려 줍니다.- Docker 이미지는
/readyz를 스스로 확인하므로,docker ps와 Coolify는 아무것도 저장하지 못하는 서버를 실행 중으로 표시하지 않고 비정상으로 표시합니다. - Oleafly에서 설정 → 공동 작업의 연결 테스트는 주소, HTTPS, 버전, 실시간 연결, 로그인 방법, 서버의 시계를 확인합니다. 관리 콘솔의 연결 점검도 같은 검사를 실행합니다.