# 공동 작업 서버 운영하기

Oleafly Server가 저장하는 것과 필요한 것, 명령 한 줄로 설치하는 방법, Docker Compose, Coolify, Render, Railway, 일반 Linux 서비스로 실행하는 방법, 그리고 첫 관리자가 되는 방법을 설명합니다.

Oleafly Server는 실시간 공동 작업을 뒷받침하는 공동 작업 서버입니다. 연구실, 학과, 기관이 자체 장비나 자체 클라우드 계정에서 운영합니다. 사람들은 Oleafly에서 서버를 추가하고, GitHub나 대학 로그인처럼 이미 가진 계정으로 로그인합니다. 누군가 서버에서 프로젝트를 공유하면, 추가된 사람들은 편집하는 동안 동기화가 유지되는 전체 사본을 받습니다. [브라우저 접근](/docs/collaboration/server-access/#browser-access)이 켜져 있으면 웹 브라우저에서 프로젝트를 열 수도 있습니다.

이 가이드는 연구실, 수업, 공저자 그룹을 위해 서버를 운영하는 사람을 위한 것입니다. 터미널을 다룰 줄 알아야 합니다. 일부 설정에서는 구성 파일도 편집해야 합니다. 코드를 작성할 필요는 없습니다.

보안 검토를 위해 [서버 보안](/security/)을 읽어 보세요. 자체 호스팅, 로그인, 기기 키, 서명된 변경, 보안 로그와 접근 로그, 소프트웨어 자재 명세서가 있는 컨테이너 이미지를 다룹니다.

## 서버가 보관하는 것

서버는 모든 것을 `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가 주소를 제공합니다. 장비에 공개 주소가 없다면 [공개 주소가 없을 때](#without-a-public-address)를 읽어 보세요.
- **사람들이 로그인할 방법**: GitHub OAuth 앱이나 소속 기관의 로그인 같은 로그인 제공자 하나 이상. 제공자가 없으면 서버가 시작되지 않습니다. 서버가 메일을 보낼 수 있는 이메일 계정은 선택 사항입니다. 있으면 관리자가 이메일로 받은 링크로 로그인하게 할 수도 있습니다. [로그인과 접근](/docs/collaboration/server-access/)을 읽어 보세요.

각 릴리스는 컨테이너 이미지 `ghcr.io/oleafly/oleafly-server`로 배포됩니다. 설치 프로그램과 Compose 파일은 [Oleafly Server 릴리스 페이지](https://github.com/Oleafly/oleafly-server/releases)에 있습니다. 단일 Linux 프로그램으로 된 서버는 [Oleafly 릴리스 페이지](https://github.com/Oleafly/Oleafly/releases)에 있습니다.

## 실행 방법 고르기

| 방법 | 사용하는 경우 |
| --- | --- |
| [명령 한 줄](#install-with-one-command) | 직접 관리하는 Linux 장비. 설치 프로그램이 Docker, Caddy, HTTPS를 설정하고 몇 가지를 묻습니다. 잘 모르겠다면 여기서 시작하세요. |
| [직접 하는 Docker Compose](#docker-compose-by-hand) | 각 파일을 직접 배치하고 편집하고 싶을 때. |
| [Coolify](#coolify) | 이미 Coolify 서버를 운영하고 있을 때. |
| [Render](#render) 또는 [Railway](#railway) | 장비를 관리하는 대신 호스팅 서비스에 비용을 내고 싶을 때. |
| [Docker 없는 Linux](#linux-without-docker) | Docker를 쓸 수 없는 대학 가상 머신. |

서버는 환경 변수에서 설정을 읽습니다. 모든 설정은 [저장소, 백업, 한도](/docs/collaboration/server-operations/#settings)에 나와 있습니다.

## 명령 한 줄로 설치하기

직접 관리하는 Linux 장비에서는 설치 프로그램이 모든 것을 설정하고 꼭 필요한 것만 묻습니다.

실행하기 전에 다음을 확인하세요.

- 장비가 x86-64나 ARM의 Linux(예: Ubuntu 24.04, Debian 13)이고 `sudo`를 쓸 수 있습니다.
- 장비의 다른 어떤 것도 80번과 443번 포트를 쓰지 않습니다. 장비 앞의 방화벽에서 TCP 80, 443 포트와 UDP 443 포트를 여세요.
- 도메인의 DNS 레코드가 장비를 가리킵니다. 아직 가리키지 않아도 설치는 끝나며, Caddy는 레코드가 준비될 때까지 인증서 발급을 계속 시도합니다.
- [로그인 제공자](/docs/collaboration/server-access/#sign-in-providers) 하나 이상의 정보가 있습니다. 예를 들어 GitHub OAuth 앱의 클라이언트 ID와 시크릿입니다. GitHub의 콜백 주소는 `https://`에 도메인을 붙이고 `/auth/callback/github`를 이어 붙인 것입니다.

:::note[베타 기간 중]
서버가 Oleafly 0.4.7-rc와 맞도록 릴리스 후보인 Oleafly Server 0.1.1-rc를 설치하세요.

```sh
curl -fsSL https://github.com/Oleafly/oleafly-server/releases/download/server-v0.1.1-rc/install.sh | sudo sh
```

아래 명령은 더 오래된 0.1.0을 설치합니다. Compose, Coolify, Render, Railway처럼 다른 방법으로 이미지를 실행한다면 `ghcr.io/oleafly/oleafly-server:0.1.1-rc`를 쓰세요.
:::

그런 다음 실행합니다.

```sh
curl -fsSL https://oleafly.com/server/install.sh | sudo sh
```

설치 프로그램은 다음을 수행합니다.

1. 장비를 확인하고 80번과 443번 포트가 비어 있는지 확인합니다.
2. Docker가 있는지 확인합니다. 없으면 설치 프로그램이 Docker의 자체 스크립트로 설치해도 되는지 묻습니다.
3. 최신 릴리스의 파일을 [Oleafly Server 릴리스](https://github.com/Oleafly/oleafly-server/releases)에서 내려받고 각 파일을 릴리스의 `SHA256SUMS`와 대조합니다. 일치하지 않는 파일이 있으면 아무것도 바꾸지 않고 멈춥니다.
4. 도메인, 서버 이름, 로그인 방법을 묻습니다. 이메일 설정과 S3 버킷에 파일 보관도 제안하며, 둘 다 선택 사항입니다.
5. 요약을 보여 주고 무엇이든 바꾸기 전에 묻습니다. 그런 다음 파일을 `/opt/oleafly-server`에 쓰고, 설정은 root만 읽을 수 있는 `.env`에 넣습니다.
6. 앞단에 Caddy를 둔 서버를 시작하고, 도메인이 HTTPS로 응답할 때까지 기다린 뒤, 주소와 설정 코드를 출력합니다.

그런 다음 [첫 관리자가 되세요](#become-the-first-admin).

설치 프로그램은 언제든 다시 실행할 수 있습니다. `/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`를 [최신 릴리스](https://github.com/Oleafly/oleafly-server/releases/latest)에서 한 폴더에 내려받으세요. 스크립트를 확인하고 읽은 다음 실행합니다.

```sh
sha256sum --check --ignore-missing SHA256SUMS
sudo sh install.sh
```

### 질문 없이 설치하기

스크립트나 프로비저닝 도구에서는 `--yes`를 붙이고 답을 환경 변수로 전달하세요. `OLEAFLY_INSTALL_DOCKER=yes`를 쓰면 Docker가 없을 때 설치 프로그램이 Docker를 추가할 수 있습니다.

```sh
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 응답을 하는지 보여 줍니다.
- **업데이트**: 먼저 [업데이트](/docs/collaboration/server-operations/#updating)에서 설명하는 대로 백업하세요. 그런 다음 아래 명령을 실행합니다. 최신 릴리스의 파일과 이미지를 내려받고, `.env`를 유지하고, 서버를 다시 시작하고, 응답할 때까지 기다립니다. 연결되어 있던 사람들은 저절로 다시 연결됩니다. 설치 프로그램은 서버를 이전 릴리스로 되돌리지 않습니다.

  ```sh
  curl -fsSL https://oleafly.com/server/install.sh | sudo sh -s -- update
  ```

- **제거**: `sudo sh /opt/oleafly-server/install.sh uninstall`은 컨테이너를 멈추고 제거합니다. 묻는 단계에서 `delete`를 입력하지 않으면 데이터와 `.env`는 남습니다. 삭제하면 서버의 모든 공유 프로젝트, 모든 계정, 보안 로그가 사라집니다. 사람들은 자기 컴퓨터에 프로젝트 사본을 그대로 가지고 있습니다.

설치 프로그램이 해결할 수 없는 문제로 멈추면 출력된 내용과 함께 [신고](https://github.com/Oleafly/oleafly-server/issues/new/choose)하세요.

## 직접 하는 Docker Compose

이 설정은 컨테이너 두 개를 실행합니다. `oleafly-server`가 서버이며 다른 컨테이너만 접근할 수 있습니다. `caddy`는 Let's Encrypt에서 인증서를 받고, 80번과 443번 포트에서 HTTPS를 제공하고, 실시간 연결을 포함한 요청을 서버로 전달합니다.

1. [Docker의 안내](https://docs.docker.com/engine/install/)에 따라 Docker Engine과 Compose 플러그인을 설치합니다.
2. 도메인의 DNS 레코드가 장비를 가리키게 합니다. 장비 앞의 방화벽에서 TCP 80, 443 포트와 UDP 443 포트를 엽니다. Caddy는 인증서를 받으려면 80번 포트가 필요합니다.
3. 서버용 폴더를 만들고, 최신 릴리스의 파일을 그 안에 내려받아 확인한 다음, 설정 파일을 만듭니다.

   ```sh
   sudo mkdir -p /opt/oleafly-server && cd /opt/oleafly-server
   base=https://github.com/Oleafly/oleafly-server/releases/latest/download
   for f in docker-compose.yml Caddyfile env.example litestream.yml SHA256SUMS; do sudo curl -fsSLO "$base/$f"; done
   sha256sum --check --ignore-missing SHA256SUMS
   sudo install -m 600 env.example .env
   ```

4. `sudoedit .env`로 `.env`를 편집합니다. `OLEAFLY_DOMAIN`은 `https://` 없이 도메인으로 설정하고, `OLEAFLY_SERVER_NAME`을 설정하고, [로그인 제공자](/docs/collaboration/server-access/#sign-in-providers)를 하나 이상 채웁니다. 쓰지 않는 제공자 줄은 비워 둡니다. 값에 `$`나 `#`이 들어 있으면 작은따옴표로 감쌉니다.
5. 시작합니다. 처음 시작할 때 릴리스 버전의 서버 이미지 `ghcr.io/oleafly/oleafly-server`를 내려받습니다.

   ```sh
   sudo docker compose up -d
   ```

6. 응답하는지 확인합니다. `200`이 출력됩니다.

   ```sh
   curl -sS -o /dev/null -w '%{http_code}\n' https://collab.example.org/healthz
   ```

7. [첫 관리자가 되세요](#become-the-first-admin). 설정 코드는 로그에 있습니다.

   ```sh
   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에 시크릿 두지 않기

시크릿을 담을 수 있는 설정은 일곱 가지입니다. `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` 줄을 삭제하세요.

```sh
sudo chown 10001:10001 secrets/github_client_secret
sudo chmod 400 secrets/github_client_secret
```

그런 다음 `docker-compose.yml` 옆에 `docker-compose.override.yml`을 만드세요. Compose가 자동으로 읽으며, 설치 프로그램은 다른 파일을 업데이트할 때 이 파일을 건드리지 않습니다.

```yaml
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_secret
```

`sudo docker compose up -d`를 다시 실행하세요.

## Coolify

Coolify는 서버 앞에 자체 프록시를 두고 인증서를 받으므로 이 설정에는 Caddy가 없습니다. Coolify는 Oleafly 저장소에서 서버를 빌드할 수도 있고, 빌드를 건너뛰는 [게시된 이미지](#deploy-the-published-image)를 실행할 수도 있습니다.

시작하기 전에 `collab.example.org` 같은 도메인의 DNS 레코드를 Coolify 서버로 지정하세요. 그런 다음 [GitHub](/docs/collaboration/server-access/#github)에서 설명하는 대로 GitHub OAuth 앱을 만들고 콜백 주소는 `https://collab.example.org/auth/callback/github`로 하세요. 클라이언트 ID와 시크릿을 가까이 두세요.

### 저장소에서 빌드하기

1. Coolify 프로젝트에서 **+ New**, **Public Repository**를 차례로 선택하고 `https://github.com/Oleafly/Oleafly`를 입력합니다. 브랜치는 `main`으로 둡니다.
2. **Build Pack**을 **Docker Compose**로, **Base Directory**를 `/`로, **Docker Compose Location**을 `/deploy/server/docker-compose.coolify.yml`로 설정한 다음 **Continue**를 선택합니다.
3. **Advanced › Build**에서 **Build arguments**를 **Managed manually in Dockerfile**로 설정합니다. 서버 이미지에는 빌드 인수가 필요하지 않습니다. 자동으로 두면 Coolify가 시크릿을 포함한 모든 변수를 이미지의 빌드 기록에 씁니다.
4. **General**에서 `oleafly-server`의 도메인을 `https://collab.example.org:8080`으로 설정하고 저장합니다. `:8080`은 서버가 듣는 포트를 Coolify의 프록시에 알려 줍니다. 사람들은 여전히 일반 HTTPS 포트로 접속하며, Coolify가 `OLEAFLY_PUBLIC_URL`을 `https://collab.example.org`로 설정해 줍니다.
5. **Environment Variables**에서 Coolify가 필수로 표시한 `OLEAFLY_SERVER_NAME`을 채운 다음 `OLEAFLY_GITHUB_CLIENT_ID`와 `OLEAFLY_GITHUB_CLIENT_SECRET`을 채웁니다. 쓰지 않는 변수는 비워 둡니다.
6. **Deploy**를 선택합니다. 첫 빌드는 서버를 컴파일하므로 몇 분이 걸립니다. 끝나면 Coolify가 리소스를 실행 중이며 정상으로 표시합니다.
7. 브라우저에서 `https://collab.example.org/healthz`를 엽니다. `{"status":"ok"}`가 표시됩니다.
8. **Logs**를 열고 `oleafly-server` 컨테이너를 선택한 다음, `Setup code:`로 시작하는 가장 최근 줄에서 코드를 복사합니다.
9. 그 코드로 [첫 관리자가 되세요](#become-the-first-admin).

서버가 시작되지 않으면 로그에 쓸 수 없는 설정이 나옵니다. `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

[Deploy to Render](https://render.com/deploy?repo=https://github.com/Oleafly/Oleafly)는 Oleafly 저장소의 Blueprint를 읽습니다. 게시된 이미지로 웹 서비스 하나를 만들고 데이터 폴더용 1 GB 디스크를 붙입니다. Render는 유료 인스턴스 유형에만 디스크를 연결하므로, 서비스는 Render의 오리건 리전에서 가장 작은 유료 유형으로 시작합니다. 다른 리전을 쓰려면 `render.yaml`에 `region`을 설정한 포크에서 배포하세요.

1. 링크를 열고 Render에 로그인합니다.
2. Render가 `OLEAFLY_SERVER_NAME`과 GitHub 클라이언트 ID와 시크릿을 묻습니다. 이름을 채우고 GitHub 필드는 지금은 비워 둡니다. 콜백 주소는 아직 알 수 없는 서비스 주소에 따라 정해지기 때문입니다.
3. **Deploy Blueprint**를 선택합니다. 서비스가 실행되면 서비스 페이지에 `https://oleafly-server.onrender.com` 같은 주소가 표시됩니다. Blueprint는 `OLEAFLY_PUBLIC_URL`을 그 주소로 설정합니다.
4. [GitHub](/docs/collaboration/server-access/#github)에서 설명하는 대로 GitHub OAuth 앱을 만들되, 콜백 주소는 그 주소 뒤에 `/auth/callback/github`를 붙인 것으로 합니다. 클라이언트 ID와 시크릿을 서비스의 **Environment**에 추가합니다. Render가 그 값으로 서버를 다시 시작합니다.
5. 서비스의 **Logs**에서 가장 최근의 `Setup code:` 줄을 찾아 [첫 관리자가 되세요](#become-the-first-admin).

서비스에 자신의 도메인을 지정했다면 **Environment**에서 `OLEAFLY_PUBLIC_URL`을 그 도메인으로 설정하고 GitHub의 콜백 주소도 그에 맞게 바꾸세요.

디스크 때문에 Render는 새 서버를 시작하기 전에 실행 중인 서버를 멈추므로, 배포할 때마다 몇 초 동안 서버를 쓸 수 없습니다. Oleafly는 저절로 다시 연결됩니다.

## Railway

Railway는 데이터 폴더용 볼륨과 함께 게시된 이미지를 실행합니다.

1. Railway 프로젝트에서 **+ New**, **Docker Image**를 차례로 선택하고 `ghcr.io/oleafly/oleafly-server:latest`를 입력합니다. 업그레이드 시점을 직접 정하려면 대신 [릴리스 페이지](https://github.com/Oleafly/Oleafly/releases)에서 릴리스 고유의 태그를 쓰세요. Railway가 첫 배포를 바로 시작할 수 있습니다. 이 배포는 `OLEAFLY_PUBLIC_URL is not set`이라는 오류로 멈추는데, 이 시점에서는 예상된 동작입니다.
2. 서비스를 엽니다. **Settings › Networking**에서 **Generate Domain**을 선택하고 포트 `8080`을 입력합니다. Railway가 `oleafly-server-production.up.railway.app` 같은 주소를 보여 줍니다.
3. **Settings › Deploy**에서 **Healthcheck Path**를 `/readyz`로 설정합니다.
4. 프로젝트 캔버스를 오른쪽 클릭해 볼륨을 추가하고, 서버의 서비스에 연결하고, 마운트 경로를 `/data`로 설정합니다.
5. **Variables**에서 **Raw Editor**를 열고 이 줄들을 자신의 서버 이름으로 붙여 넣습니다. GitHub 값은 [GitHub](/docs/collaboration/server-access/#github)를 따르세요. 콜백 주소는 2단계의 주소 앞에 `https://`를, 뒤에 `/auth/callback/github`를 붙인 것입니다.

   ```ini
   OLEAFLY_PUBLIC_URL=https://${{RAILWAY_PUBLIC_DOMAIN}}
   OLEAFLY_BIND=0.0.0.0:8080
   OLEAFLY_DATA_DIR=/data
   OLEAFLY_BEHIND_PROXY=true
   OLEAFLY_SERVER_NAME=Smith Lab
   OLEAFLY_GITHUB_CLIENT_ID=Ov23liExampleClientId
   OLEAFLY_GITHUB_CLIENT_SECRET=example-client-secret
   PORT=8080
   RAILWAY_RUN_UID=0
   ```

   Railway는 볼륨을 root로 마운트합니다. `RAILWAY_RUN_UID=0`은 서버가 볼륨에 쓸 수 있도록 root로 실행합니다.

6. 변경 사항을 배포합니다. 서비스의 **Deploy Logs**에서 가장 최근의 `Setup code:` 줄을 찾아 [첫 관리자가 되세요](#become-the-first-admin).

## Docker 없는 Linux

Docker가 없는 장비에서는 서버가 systemd 아래에서 단일 프로그램으로 실행되고, 앞단에 HTTPS용 Caddy를 둡니다.

### 서버 내려받기

[릴리스 페이지](https://github.com/Oleafly/Oleafly/releases)의 서버 릴리스마다 x86-64와 ARM용으로 미리 빌드된 프로그램과, 확인에 쓰는 `SHA256SUMS` 파일이 있습니다. 이 프로그램은 다른 것을 설치하지 않아도 실행됩니다.

장비에 맞는 아카이브(이름이 `x86_64-unknown-linux-musl.tar.gz` 또는 `aarch64-unknown-linux-musl.tar.gz`로 끝남)와 `SHA256SUMS`를 한 폴더에 내려받으세요. 그런 다음 확인하고 설치합니다. ARM 장비에서는 `x86_64` 대신 `aarch64`를 쓰세요.

```sh
sha256sum --check --ignore-missing SHA256SUMS
tar -xzf oleafly-server-*-x86_64-unknown-linux-musl.tar.gz
sudo install -m 0755 oleafly-server-*-x86_64-unknown-linux-musl/oleafly-server /usr/local/bin/oleafly-server
oleafly-server --version
```

GitHub 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`를 쓰세요.

```sh
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로 실행하기

1. 설정 파일을 만듭니다. root만 읽을 수 있습니다.

   ```sh
   sudo install -d -m 0755 /etc/oleafly-server
   sudo install -m 0600 /dev/null /etc/oleafly-server/oleafly-server.env
   sudoedit /etc/oleafly-server/oleafly-server.env
   ```

   한 줄에 설정 하나씩 넣습니다. `OLEAFLY_BIND=127.0.0.1:8080`은 서버를 네트워크에 노출하지 않아 Caddy만 접근할 수 있게 합니다. 유닛이 `OLEAFLY_DATA_DIR`을 설정하므로 직접 설정하지 마세요.

   ```ini
   OLEAFLY_PUBLIC_URL=https://collab.example.org
   OLEAFLY_BIND=127.0.0.1:8080
   OLEAFLY_BEHIND_PROXY=true
   OLEAFLY_SERVER_NAME=Smith Lab
   OLEAFLY_GITHUB_CLIENT_ID=Ov23liExampleClientId
   OLEAFLY_GITHUB_CLIENT_SECRET=example-client-secret
   ```

2. 압축을 푼 아카이브나 저장소 클론의 `deploy/server`에서 유닛을 설치하고 시작합니다. 그런 다음 설정 코드를 찾습니다.

   ```sh
   sudo install -m 0644 oleafly-server.service /etc/systemd/system/oleafly-server.service
   sudo systemctl daemon-reload
   sudo systemctl enable --now oleafly-server
   sudo 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`를 실행해 다음을 추가하세요.

```ini
[Service]
LoadCredential=github-client-secret:/etc/oleafly-server/github-client-secret
Environment=OLEAFLY_GITHUB_CLIENT_SECRET_FILE=%d/github-client-secret
```

그런 다음 `sudo systemctl restart oleafly-server`를 실행하세요.

### 앞단에 HTTPS 두기

[배포판별 안내](https://caddyserver.com/docs/install)에 따라 Caddy를 설치하세요. `/etc/caddy/Caddyfile`을 이 줄들로 바꾸고 `sudo systemctl reload caddy`를 실행하세요. Caddy가 인증서를 받고 실시간 연결을 그대로 통과시킵니다.

```
collab.example.org {
	reverse_proxy 127.0.0.1:8080
}
```

nginx나 Apache, 또는 대학이 이미 운영하는 웹 서버를 쓰려면 [리버스 프록시 뒤에서](/docs/collaboration/server-operations/#behind-a-reverse-proxy)를 읽어 보세요.

## 공개 주소가 없을 때

장비에 공개 주소가 없다면, 예를 들어 대학 방화벽 뒤에 있는 연구실 컴퓨터라면 Cloudflare Tunnel로 접근할 수 있게 만들 수 있습니다. 도메인을 등록한 Cloudflare 계정이 필요합니다. Cloudflare가 호스트 이름의 HTTPS를 처리하므로, 요청은 내 장비에 도달하기 전에 Cloudflare 네트워크에서 복호화됩니다. 서버로 가는 트래픽을 읽을 수 있는 주체에 Cloudflare도 포함하세요.

1. `.env`를 편집하는 단계까지 [직접 하는 Docker Compose](#docker-compose-by-hand)의 단계를 따릅니다. `OLEAFLY_DOMAIN`은 `collab.example.org` 같이 쓸 호스트 이름으로 설정합니다. 명령 한 줄 설치 프로그램은 Caddy를 시작하므로 여기에는 맞지 않습니다.
2. 서버만 시작합니다. 여기서는 Caddy가 필요 없습니다.

   ```sh
   sudo docker compose up -d oleafly-server
   ```

3. Cloudflare 대시보드에서 **Networking › Tunnels**로 가서 **Create Tunnel**을 선택하고, 이름을 붙이고, **Create Tunnel**을 다시 선택합니다. 표시되는 설치 명령에서 토큰을 복사합니다.
4. 서버 옆에서 터널을 시작합니다. `read` 명령은 토큰을 붙여 넣을 때까지 기다리며 토큰을 화면에 표시하지 않습니다.

   ```sh
   read -rs TUNNEL_TOKEN && export TUNNEL_TOKEN
   sudo --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
   ```

5. 대시보드로 돌아와 터널을 엽니다. **Routes**에서 **Add route**, **Published application**을 차례로 선택합니다. **Hostname**에 서브도메인을 입력하고 도메인을 고릅니다. **Service URL**을 `http://oleafly-server:8080`으로 설정하고 **Add route**를 선택합니다.
6. `https://collab.example.org/healthz`에서 응답하는지 확인한 다음 [첫 관리자가 되세요](#become-the-first-admin).

Docker가 없는 장비에서는 [Cloudflare의 패키지 저장소](https://pkg.cloudflare.com/)에서 `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`입니다.

## 첫 관리자 되기

새 서버에는 관리자가 없습니다. 누군가 설정을 마칠 때까지 서버는 시작할 때마다 일회용 설정 코드를 새로 만들어 로그에 씁니다.

1. 로그에서 `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'`
2. Oleafly에서 **설정 → 공동 작업**을 열고 **서버 추가**를 선택한 다음 서버 주소를 입력합니다. Oleafly가 서버에 설정이 필요한 것을 알아보고 **설정 코드**를 묻습니다.
3. 코드를 입력하고 설정해 둔 제공자 중 아무것으로 로그인합니다. 내가 서버의 관리자가 되고 코드는 더 이상 쓸 수 없게 됩니다.

코드를 사용하기 전에 코드를 가진 사람은 누구나 자신을 관리자로 만들 수 있으므로, 코드는 Oleafly에만 붙여 넣으세요.

`OLEAFLY_SETUP_CODE`로 코드를 직접 정할 수도 있습니다. 문자나 숫자 12자 이상이며 원하면 대시나 공백을 넣을 수 있습니다. 그러면 서버는 코드를 출력하지 않습니다. 로그에는 `Setup code: set by OLEAFLY_SETUP_CODE`라고만 나오며, 정해 둔 값을 입력하면 됩니다. 설정이 끝나면 설정에서 제거하세요.

다음으로 사람들을 들이세요. 방법은 [로그인과 접근](/docs/collaboration/server-access/#access-rules)에서 설명합니다.

## 서버 확인하기

- 명령 한 줄 설치에서는 `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, 버전, 실시간 연결, 로그인 방법, 서버의 시계를 확인합니다. [관리 콘솔](/docs/collaboration/server-access/#admin-console)의 **연결 점검**도 같은 검사를 실행합니다.
