Chạy máy chủ
Chạy một máy chủ cộng tác
Oleafly Server lưu trữ những gì, cần những gì, cách cài đặt nó bằng một lệnh hoặc chạy nó với Docker Compose, Coolify, Render, Railway hay một dịch vụ Linux thông thường, rồi trở thành quản trị viên đầu tiên của nó.
Oleafly Server là máy chủ cộng tác đứng sau tính năng cộng tác trực tiếp. Phòng thí nghiệm, bộ phận hay tổ chức của bạn tự chạy nó trên máy của mình hoặc trong tài khoản đám mây riêng của mình. Mọi người thêm nó trong Oleafly và đăng nhập bằng một tài khoản họ đã có, chẳng hạn GitHub hoặc đăng nhập của trường đại học. Khi ai đó chia sẻ một dự án trên máy chủ, những người họ thêm vào sẽ nhận được một bản sao đầy đủ luôn được đồng bộ trong khi họ chỉnh sửa. Khi bật quyền truy cập qua trình duyệt, họ cũng có thể mở dự án trong trình duyệt web.
Tài liệu này dành cho người vận hành máy chủ cho một phòng thí nghiệm, một khóa học hoặc một nhóm đồng tác giả. Bạn cần thành thạo việc dùng terminal. Một số cách thiết lập còn yêu cầu bạn chỉnh sửa một tệp cấu hình. Bạn không cần viết mã.
Để rà soát bảo mật, hãy đọc Bảo mật máy chủ. Tài liệu đó đề cập việc tự triển khai, đăng nhập, khóa thiết bị, các thay đổi có chữ ký, nhật ký bảo mật và truy cập, cùng image container kèm danh mục phần mềm của nó.
Máy chủ lưu trữ những gì
Phần tiêu đề “Máy chủ lưu trữ những gì”Máy chủ lưu mọi thứ trong một thư mục dữ liệu, do OLEAFLY_DATA_DIR chỉ định:
- Tài khoản: tên hiển thị của từng thành viên, địa chỉ ảnh đại diện, các địa chỉ email đã xác minh, cùng ID người dùng và tên đăng nhập của họ tại nhà cung cấp đăng nhập. Máy chủ không bao giờ nhìn thấy hay lưu trữ mật khẩu.
- Thiết bị: từng máy tính đã đăng nhập, kèm tên, hệ điều hành, khóa công khai và thời điểm nó được nhìn thấy lần cuối. Mã thông báo đăng nhập chỉ được lưu dưới dạng băm.
- Nhật ký bảo mật: các lần đăng nhập và đăng nhập bị từ chối, thiết bị được thêm vào và đăng xuất, các thay đổi về thành viên, vai trò và cài đặt, dự án được chia sẻ, lưu trữ và khôi phục, thay đổi về việc ai có thể mở một dự án, và các lời mời khách. Mỗi mục ghi có thời gian và địa chỉ IP.
- Cài đặt máy chủ mà các quản trị viên thay đổi trong Oleafly.
- Nhật ký truy cập dự án, cho những dự án mà chủ sở hữu bật nó lên: ai đã mở dự án, tham gia vào nó hay tải xuống một bản sao, kèm tên thiết bị và thời gian. Chỉ chủ sở hữu của dự án mới đọc được nó.
- Lời mời khách: địa chỉ email được mời, dự án, vai trò và người gửi lời mời.
- Dự án dùng chung: mọi tệp và toàn bộ lịch sử thay đổi, cùng các bình luận, đề xuất, tin nhắn trò chuyện và tên phiên bản thuộc về chúng.
- PDF đã biên dịch: với mỗi dự án dùng chung, PDF mới nhất và tệp SyncTeX của nó mà ứng dụng của một chủ sở hữu hoặc người chỉnh sửa đã gửi lên sau một lần biên dịch thành công, kèm người biên dịch và thời điểm biên dịch.
Các mục trong nhật ký bảo mật và nhật ký truy cập, cùng các lời mời khách đã được trả lời hoặc đã hết hạn, bị xóa sau OLEAFLY_SECURITY_LOG_DAYS ngày, mặc định là 365 ngày. Những tệp mà một dự án không còn dùng, chẳng hạn bản sao cũ của một hình ảnh đã bị thay thế, bị xóa 30 ngày sau lần cuối dự án dùng đến chúng. Mỗi PDF đã biên dịch thay thế bản trước nó. Khi một chủ sở hữu ngừng chia sẻ một dự án, máy chủ giữ nó ở chế độ chỉ đọc trong OLEAFLY_ARCHIVE_DAYS ngày, mặc định là 30 ngày, rồi xóa nó. Trong khoảng thời gian đó, chỉ chủ sở hữu và các quản trị viên trong dự án mới tải xuống được.
Ai có thể đọc các dự án
Phần tiêu đề “Ai có thể đọc các dự án”Các dự án không được mã hóa trên máy chủ. Bất kỳ ai đọc được thư mục dữ liệu, đĩa của máy hoặc bản sao lưu của bạn đều đọc được mọi dự án được lưu ở đó. Điều đó bao gồm cả người vận hành máy và công ty lưu trữ nó.
Bên trong Oleafly, các quy tắc chặt chẽ hơn. Không vai trò nào trên máy chủ, kể cả quản trị viên, có thể mở một dự án, trừ khi chủ sở hữu của dự án đó thêm họ vào. Nếu một dự án phải tránh xa những người vận hành máy chủ, hãy chạy một máy chủ riêng cho nó.
Máy của từng thành viên cũng giữ một bản sao đầy đủ của mỗi dự án được chia sẻ với họ. Hãy yêu cầu các thành viên bật mã hóa đĩa, chẳng hạn FileVault trên macOS, BitLocker trên Windows hoặc LUKS trên Linux.
Những gì bạn cần
Phần tiêu đề “Những gì bạn cần”- Một máy luôn bật. Bất kỳ máy Linux nào cũng được, hoặc một tài khoản với dịch vụ lưu trữ như Render hay Railway. Một máy ảo nhỏ là đủ để bắt đầu. Hãy theo dõi bộ nhớ và đĩa của nó khi các dự án lớn dần. Máy chủ chạy trên x86-64 và ARM.
- Một tên miền cho máy chủ, chẳng hạn
collab.example.org, với bản ghi DNS trỏ đến máy. Render và Railway cấp cho bạn một địa chỉ nếu bạn chưa có. Nếu máy không có địa chỉ công khai, hãy đọc Khi không có địa chỉ công khai. - Một cách để mọi người đăng nhập: ít nhất một nhà cung cấp đăng nhập, chẳng hạn một ứng dụng GitHub OAuth hoặc đăng nhập của tổ chức bạn. Máy chủ sẽ không khởi động nếu thiếu nó. Một tài khoản email mà máy chủ có thể dùng để gửi thư là tùy chọn. Có nó, quản trị viên còn có thể cho phép mọi người đăng nhập bằng liên kết gửi qua email. Đọc Đăng nhập và truy cập.
Mỗi bản phát hành được xuất bản dưới dạng một image container, ghcr.io/oleafly/oleafly-server. Trình cài đặt và các tệp Compose của nó nằm trên trang phát hành Oleafly Server (mở trong thẻ mới). Máy chủ dưới dạng một chương trình Linux đơn lẻ nằm trên trang phát hành Oleafly (mở trong thẻ mới).
Chọn cách chạy
Phần tiêu đề “Chọn cách chạy”| Tùy chọn | Khi nào dùng |
|---|---|
| Một lệnh | Một máy Linux do bạn tự quản lý. Trình cài đặt dựng sẵn Docker, Caddy và HTTPS, và hỏi vài câu hỏi. Hãy bắt đầu từ đây nếu bạn chưa chắc chắn. |
| Docker Compose thủ công | Bạn muốn tự đặt và tự chỉnh từng tệp. |
| Coolify | Bạn đã chạy một máy chủ Coolify. |
| Render hoặc Railway | Bạn muốn trả tiền cho một dịch vụ lưu trữ hơn là tự quản lý một máy. |
| Linux không dùng Docker | Một máy ảo của trường đại học nơi bạn không thể dùng Docker. |
Máy chủ đọc cài đặt của nó từ các biến môi trường. Lưu trữ, sao lưu và giới hạn liệt kê tất cả chúng.
Cài đặt bằng một lệnh
Phần tiêu đề “Cài đặt bằng một lệnh”Trên một máy Linux do bạn tự quản lý, trình cài đặt dựng mọi thứ và chỉ hỏi những gì nó cần biết.
Trước khi chạy, hãy kiểm tra rằng:
- Máy chạy Linux trên x86-64 hoặc ARM, chẳng hạn Ubuntu 24.04 hoặc Debian 13, và bạn có thể dùng
sudotrên đó. - Không có gì khác trên máy dùng cổng 80 và 443. Mở cổng TCP 80 và 443 cùng cổng UDP 443 trong bất kỳ tường lửa nào đứng trước nó.
- Bản ghi DNS của tên miền bạn trỏ đến máy. Nếu chưa trỏ, việc cài đặt vẫn hoàn tất, và Caddy tiếp tục thử lấy chứng chỉ cho đến khi bản ghi sẵn sàng.
- Bạn có thông tin của ít nhất một nhà cung cấp đăng nhập, chẳng hạn client ID và secret của một ứng dụng GitHub OAuth. Với GitHub, địa chỉ callback là
https://cùng tên miền của bạn, theo sau là/auth/callback/github.
Sau đó chạy:
curl -fsSL https://oleafly.com/server/install.sh | sudo shTrình cài đặt sẽ:
- Kiểm tra máy, và rằng cổng 80 và 443 còn trống.
- Kiểm tra Docker. Nếu thiếu, trình cài đặt hỏi trước khi cài nó bằng chính script của Docker.
- Tải các tệp của bản phát hành mới nhất từ các bản phát hành Oleafly Server (mở trong thẻ mới) và kiểm tra từng tệp với
SHA256SUMScủa bản phát hành. Nếu một tệp không khớp, nó dừng lại mà không thay đổi gì. - Hỏi tên miền của bạn, tên của máy chủ và cách mọi người đăng nhập. Nó cũng đề nghị thiết lập email và giữ các tệp trong một S3 bucket. Cả hai đều là tùy chọn.
- Hiện một bản tóm tắt và hỏi trước khi thay đổi bất cứ điều gì. Rồi nó ghi các tệp của mình vào
/opt/oleafly-server, với cài đặt của bạn trong.env, mà chỉ root mới đọc được. - Khởi động máy chủ với Caddy đứng trước, chờ cho đến khi tên miền của bạn trả lời qua HTTPS, và in ra địa chỉ cùng mã thiết lập.
Sau đó trở thành quản trị viên đầu tiên.
Bạn có thể chạy trình cài đặt lại bất kỳ lúc nào. Khi nó tìm thấy một máy chủ trong /opt/oleafly-server, nó giữ nguyên .env, đặt lại các tệp khác và khởi động lại máy chủ. Điều đó sửa được phần lớn các thiết lập hỏng.
Dữ liệu của bạn nằm trong Docker volume oleafly-server_oleafly-data. Để cài ở nơi khác ngoài /opt/oleafly-server, hãy đặt OLEAFLY_DIR, ví dụ curl -fsSL https://oleafly.com/server/install.sh | sudo OLEAFLY_DIR=/srv/oleafly sh, và dùng thư mục đó trong các lệnh bên dưới.
Đọc trình cài đặt trước
Phần tiêu đề “Đọc trình cài đặt trước”Nếu tổ chức của bạn không cho phép đưa một script thẳng vào shell, hãy tải install.sh và SHA256SUMS từ bản phát hành mới nhất (mở trong thẻ mới) vào một thư mục. Kiểm tra script, đọc nó, rồi chạy:
sha256sum --check --ignore-missing SHA256SUMSsudo sh install.shCài đặt không cần câu hỏi
Phần tiêu đề “Cài đặt không cần câu hỏi”Để dùng trong một script hoặc công cụ provisioning, thêm --yes và truyền các câu trả lời qua biến môi trường. OLEAFLY_INSTALL_DOCKER=yes cho phép trình cài đặt thêm Docker nếu nó còn thiếu.
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 -- --yesTrình cài đặt dùng mọi cài đặt nó tìm thấy trong môi trường mà không hỏi, có hoặc không có --yes. sudo sh /opt/oleafly-server/install.sh --help liệt kê tất cả, gồm OpenID Connect, email và S3. Các giá trị gõ trên dòng lệnh có thể rơi vào lịch sử shell của bạn, nên một công cụ provisioning cần truyền các secret từ kho secret riêng của nó.
Trạng thái, cập nhật và gỡ cài đặt
Phần tiêu đề “Trạng thái, cập nhật và gỡ cài đặt”-
Trạng thái:
sudo sh /opt/oleafly-server/install.sh statuscho biết máy chủ có đang chạy hay không và tên miền của bạn có trả lời qua HTTPS với một chứng chỉ hợp lệ hay không. -
Cập nhật: sao lưu trước, như phần Cập nhật giải thích. Rồi chạy lệnh bên dưới. Nó tải các tệp và image của bản phát hành mới nhất, giữ nguyên
.env, khởi động lại máy chủ và chờ cho đến khi nó trả lời. Những người đang kết nối sẽ tự kết nối lại. Trình cài đặt không bao giờ hạ máy chủ xuống một bản phát hành cũ hơn.Cửa sổ terminal curl -fsSL https://oleafly.com/server/install.sh | sudo sh -s -- update -
Gỡ cài đặt:
sudo sh /opt/oleafly-server/install.sh uninstalldừng và xóa các container. Dữ liệu và.envcủa bạn vẫn còn, trừ khi bạn gõdeletekhi nó hỏi. Việc xóa chúng sẽ xóa mọi dự án dùng chung trên máy chủ, mọi tài khoản và nhật ký bảo mật. Mọi người vẫn giữ các bản sao dự án của riêng họ trên máy tính của mình.
Nếu trình cài đặt dừng lại với một vấn đề bạn không sửa được, hãy báo cáo nó (mở trong thẻ mới) kèm những gì nó in ra.
Docker Compose thủ công
Phần tiêu đề “Docker Compose thủ công”Cách thiết lập này chạy hai container. oleafly-server là máy chủ, và chỉ các container khác mới tiếp cận được nó. caddy lấy chứng chỉ từ Let’s Encrypt, phục vụ HTTPS trên cổng 80 và 443, và chuyển các yêu cầu đến máy chủ, kể cả các kết nối thời gian thực.
-
Cài Docker Engine và plugin Compose theo hướng dẫn của Docker (mở trong thẻ mới).
-
Trỏ bản ghi DNS của tên miền bạn đến máy. Mở cổng TCP 80 và 443 cùng cổng UDP 443 trong bất kỳ tường lửa nào đứng trước nó. Caddy cần cổng 80 để lấy chứng chỉ.
-
Tạo một thư mục cho máy chủ, tải các tệp của bản phát hành mới nhất vào đó, kiểm tra chúng, và tạo tệp cài đặt của bạn:
Cửa sổ terminal 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 -
Chỉnh sửa
.envbằngsudoedit .env. ĐặtOLEAFLY_DOMAINthành tên miền của bạn, không kèmhttps://, đặtOLEAFLY_SERVER_NAME, và điền ít nhất một nhà cung cấp đăng nhập. Để trống các dòng nhà cung cấp mà bạn không dùng. Đặt một giá trị trong dấu nháy đơn nếu nó chứa$hoặc#. -
Khởi động. Lần khởi động đầu tải image của máy chủ,
ghcr.io/oleafly/oleafly-server, ở phiên bản của bản phát hành.Cửa sổ terminal sudo docker compose up -d -
Kiểm tra rằng nó trả lời. Lệnh này in ra
200:Cửa sổ terminal curl -sS -o /dev/null -w '%{http_code}\n' https://collab.example.org/healthz -
Trở thành quản trị viên đầu tiên. Mã thiết lập nằm trong nhật ký:
Cửa sổ terminal sudo docker compose logs oleafly-server | grep 'Setup code'
Dữ liệu của bạn nằm trong Docker volume oleafly-server_oleafly-data. Caddy giữ chứng chỉ của nó trong oleafly-server_caddy-data.
Docker tự mở cổng 80 và 443, kể cả khi một tường lửa máy chủ như ufw đang bật. Đó là điều Caddy cần. Đừng thêm mục ports: vào dịch vụ oleafly-server. Để tiếp cận máy chủ từ chính máy đó, hãy publish nó dưới dạng 127.0.0.1:8080:8080 để nó không lộ ra mạng.
Nếu bạn thay đổi Caddyfile, hãy chạy sudo docker compose up -d --force-recreate caddy. Để cập nhật về sau, tải các tệp của bản phát hành mới theo cách tương tự và chạy lại sudo docker compose up -d.
Giữ các secret ra khỏi .env
Phần tiêu đề “Giữ các secret ra khỏi .env”Bảy cài đặt có thể chứa secret: OLEAFLY_SETUP_CODE, OLEAFLY_GITHUB_CLIENT_SECRET, OLEAFLY_OIDC_<NAME>_CLIENT_SECRET, OLEAFLY_SMTP_URL, OLEAFLY_BLOB_STORE, OLEAFLY_S3_ACCESS_KEY_ID và OLEAFLY_S3_SECRET_ACCESS_KEY. Mỗi cái còn có một phiên bản _FILE chỉ định một tệp giữ giá trị đó. Chỉ đặt một trong hai, không đặt cả hai.
Ví dụ, để truyền client secret của GitHub dưới dạng một Docker secret, hãy lưu nó trong secrets/github_client_secret cạnh docker-compose.yml, cho người dùng của máy chủ (ID 10001) đọc được nó, và xóa dòng OLEAFLY_GITHUB_CLIENT_SECRET khỏi .env:
sudo chown 10001:10001 secrets/github_client_secretsudo chmod 400 secrets/github_client_secretRồi tạo docker-compose.override.yml cạnh docker-compose.yml. Compose tự đọc nó, và trình cài đặt không đụng đến nó khi cập nhật các tệp khác.
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_secretChạy lại sudo docker compose up -d.
Coolify
Phần tiêu đề “Coolify”Coolify đặt proxy riêng của nó đứng trước máy chủ và lấy chứng chỉ, nên cách thiết lập này không có Caddy. Coolify có thể dựng máy chủ từ kho mã Oleafly, hoặc chạy image đã xuất bản, vốn bỏ qua bước dựng.
Trước khi bắt đầu, hãy trỏ bản ghi DNS của tên miền bạn, chẳng hạn collab.example.org, đến máy chủ Coolify. Rồi tạo ứng dụng GitHub OAuth như mô tả ở phần GitHub, với địa chỉ callback https://collab.example.org/auth/callback/github. Giữ sẵn client ID và secret của ứng dụng.
Dựng từ kho mã
Phần tiêu đề “Dựng từ kho mã”- Trong dự án Coolify của bạn, chọn + New, rồi Public Repository, và nhập
https://github.com/Oleafly/Oleafly. Giữ nguyên nhánhmain. - Đặt Build Pack thành Docker Compose, Base Directory thành
/và Docker Compose Location thành/deploy/server/docker-compose.coolify.yml, rồi chọn Continue. - Dưới Advanced › Build, đặt Build arguments thành Managed manually in Dockerfile. Image của máy chủ không cần tham số dựng. Nếu để chế độ tự động, Coolify sẽ ghi mọi biến, kể cả các secret, vào lịch sử dựng của image.
- Dưới General, đặt tên miền của
oleafly-serverthànhhttps://collab.example.org:8080rồi lưu. Phần:8080cho proxy của Coolify biết máy chủ lắng nghe trên cổng nào. Mọi người vẫn kết nối trên cổng HTTPS thông thường, và Coolify tự đặtOLEAFLY_PUBLIC_URLthànhhttps://collab.example.orgcho bạn. - Dưới Environment Variables, điền
OLEAFLY_SERVER_NAME, mà Coolify đánh dấu là bắt buộc, rồiOLEAFLY_GITHUB_CLIENT_IDvàOLEAFLY_GITHUB_CLIENT_SECRET. Để trống các biến mà bạn không dùng. - Chọn Deploy. Lần dựng đầu tiên biên dịch máy chủ và mất vài phút. Khi hoàn tất, Coolify hiển thị tài nguyên đang chạy và ổn định.
- Mở
https://collab.example.org/healthztrong trình duyệt. Nó hiển thị{"status":"ok"}. - Mở Logs, chọn container
oleafly-server, và sao chép mã từ dòng mới nhất bắt đầu bằngSetup code:. - Trở thành quản trị viên đầu tiên với mã đó.
Nếu máy chủ không khởi động, nhật ký của nó sẽ nêu tên cài đặt mà nó không dùng được. Khi nhật ký nói OLEAFLY_PUBLIC_URL chưa được đặt, tức là thiếu bước 4. Một tên miền bắt đầu bằng http:// sẽ bị từ chối, vì máy chủ cần HTTPS.
Nếu Cloudflare đứng trước Coolify, vì bản ghi DNS của bạn đi qua proxy của Cloudflare hoặc một tunnel dẫn đến proxy của Coolify, hãy đặt OLEAFLY_PROXY_HOPS thành 2. Nếu không, nhật ký bảo mật sẽ hiển thị địa chỉ của proxy cho tất cả mọi người, và họ dùng chung một giới hạn đăng nhập.
Tệp Coolify có chỗ cho GitHub và một nhà cung cấp OpenID Connect tên UNIVERSITY. Đặt OLEAFLY_OIDC_UNIVERSITY_LABEL thành văn bản mọi người sẽ thấy, chẳng hạn GitLab. Địa chỉ callback của nó kết thúc bằng /auth/callback/university. Để thêm nhà cung cấp khác, hãy triển khai từ một fork với bản sao tệp riêng của bạn.
Dữ liệu nằm trong một Docker volume có tên kết thúc bằng oleafly-data. Tìm nó bằng docker volume ls --filter name=oleafly-data. Image không có shell, nên Terminal của Coolify không thể mở một shell trong container của máy chủ. Nhật ký và health check hoạt động như thường lệ.
Triển khai image đã xuất bản
Phần tiêu đề “Triển khai image đã xuất bản”Chạy image đã xuất bản sẽ bỏ qua bước dựng, phù hợp với một máy chủ Coolify nhỏ. Làm theo các bước trên với hai thay đổi. Ở bước 2, đặt Docker Compose Location thành /deploy/server/docker-compose.coolify-image.yml. Bỏ qua bước 3, vì không có gì được dựng. Tệp theo dõi một chuỗi bản phát hành, nên mỗi lần Redeploy sẽ kéo bản phát hành mới nhất trong chuỗi đó.
Render
Phần tiêu đề “Render”Deploy to Render (mở trong thẻ mới) đọc Blueprint trong kho mã Oleafly. Nó tạo một dịch vụ web từ image đã xuất bản, với một đĩa 1 GB cho thư mục dữ liệu. Render chỉ gắn đĩa vào các loại instance trả phí, nên dịch vụ khởi động trên loại trả phí nhỏ nhất, trong khu vực Oregon của Render. Để dùng khu vực khác, hãy triển khai từ một fork với region được đặt trong render.yaml.
- Mở liên kết và đăng nhập vào Render.
- Render hỏi
OLEAFLY_SERVER_NAMEcùng client ID và secret của GitHub. Điền tên và để trống các trường GitHub trong lúc này. Địa chỉ callback của chúng phụ thuộc vào địa chỉ dịch vụ, mà bạn chưa có. - Chọn Deploy Blueprint. Khi dịch vụ hoạt động, trang của nó hiển thị địa chỉ, chẳng hạn
https://oleafly-server.onrender.com. Blueprint đặtOLEAFLY_PUBLIC_URLthành địa chỉ đó. - Tạo ứng dụng GitHub OAuth như mô tả ở phần GitHub, với địa chỉ đó theo sau
/auth/callback/githublàm địa chỉ callback. Thêm client ID và secret dưới Environment của dịch vụ. Render khởi động lại máy chủ với các giá trị đó. - Tìm dòng
Setup code:mới nhất trong Logs của dịch vụ và trở thành quản trị viên đầu tiên.
Nếu bạn gán cho dịch vụ tên miền riêng của mình, hãy đặt OLEAFLY_PUBLIC_URL thành nó dưới Environment và đổi địa chỉ callback tại GitHub cho khớp.
Vì có đĩa, Render dừng máy chủ đang chạy trước khi khởi động máy chủ mới, nên mỗi lần triển khai làm máy chủ gián đoạn vài giây. Oleafly tự kết nối lại.
Railway
Phần tiêu đề “Railway”Railway chạy image đã xuất bản, với một volume cho thư mục dữ liệu.
-
Trong một dự án Railway, chọn + New, rồi Docker Image, và nhập
ghcr.io/oleafly/oleafly-server:latest. Để tự chọn thời điểm nâng cấp, hãy dùng tag riêng của một bản phát hành từ trang phát hành (mở trong thẻ mới) thay thế. Railway có thể bắt đầu một lần triển khai đầu tiên ngay lập tức. Nó dừng vớiOLEAFLY_PUBLIC_URL is not set, điều này là bình thường ở giai đoạn này. -
Mở dịch vụ. Dưới Settings › Networking, chọn Generate Domain và nhập cổng
8080. Railway hiển thị địa chỉ, chẳng hạnoleafly-server-production.up.railway.app. -
Dưới Settings › Deploy, đặt Healthcheck Path thành
/readyz. -
Nhấp chuột phải vào khung dự án, thêm một volume, gắn nó vào dịch vụ của máy chủ và đặt đường dẫn gắn của nó thành
/data. -
Dưới Variables, mở Raw Editor và dán các dòng sau với tên máy chủ của riêng bạn. Với các giá trị GitHub, làm theo phần GitHub. Địa chỉ callback là địa chỉ của bạn từ bước 2, với
https://đứng trước và/auth/callback/githubđứng sau.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 gắn volume với quyền root.
RAILWAY_RUN_UID=0chạy máy chủ dưới quyền root để nó ghi được vào volume. -
Triển khai các thay đổi. Tìm dòng
Setup code:mới nhất trong Deploy Logs của dịch vụ và trở thành quản trị viên đầu tiên.
Linux không dùng Docker
Phần tiêu đề “Linux không dùng Docker”Trên một máy không có Docker, máy chủ chạy như một chương trình đơn lẻ dưới systemd, với Caddy đứng trước cho HTTPS.
Tải xuống máy chủ
Phần tiêu đề “Tải xuống máy chủ”Mỗi bản phát hành máy chủ trên trang phát hành (mở trong thẻ mới) có một chương trình dựng sẵn cho x86-64 và cho ARM, cùng một tệp SHA256SUMS để kiểm tra. Chương trình không cần cài thêm gì khác.
Tải bản nén cho máy của bạn, kết thúc bằng x86_64-unknown-linux-musl.tar.gz hoặc aarch64-unknown-linux-musl.tar.gz, cùng SHA256SUMS vào một thư mục. Rồi kiểm tra và cài đặt. Trên máy ARM, dùng aarch64 thay cho x86_64:
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 --versionNếu đã cài GitHub CLI, lệnh gh attestation verify oleafly-server-*-x86_64-unknown-linux-musl.tar.gz --repo Oleafly/Oleafly còn kiểm tra rằng GitHub đã dựng bản nén đó từ kho mã Oleafly. Bản nén gồm cả unit systemd, oleafly-server.service.
Để tự dựng chương trình thay vì tải, hãy chạy lệnh này từ một bản clone của kho mã Oleafly trên bất kỳ máy tính nào có Docker. Dùng --platform linux/arm64 cho một máy chủ ARM.
docker buildx build --platform linux/amd64 --target binary --output type=local,dest=dist -f crates/oleafly-server/Dockerfile .Lệnh này ghi ra dist/oleafly-server. Sao chép nó vào /usr/local/bin/oleafly-server trên máy chủ và cấp quyền thực thi cho nó.
Chạy với systemd
Phần tiêu đề “Chạy với systemd”-
Tạo tệp cài đặt. Chỉ root mới đọc được nó:
Cửa sổ terminal 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Đặt mỗi cài đặt trên một dòng.
OLEAFLY_BIND=127.0.0.1:8080giữ máy chủ ngoài mạng để chỉ Caddy tiếp cận được nó. Đừng đặtOLEAFLY_DATA_DIR, vì unit đã đặt nó sẵn.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 -
Cài đặt và khởi động unit từ bản nén đã giải nén, hoặc từ
deploy/servertrong một bản clone của kho mã. Rồi tìm mã thiết lập:Cửa sổ terminal 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'
Unit chạy máy chủ dưới một người dùng mà systemd tạo cho nó, với chế độ chỉ đọc đối với phần còn lại của hệ thống. Nơi duy nhất nó ghi được là /var/lib/oleafly-server, nơi nó giữ dữ liệu của mình. Trên đĩa, thư mục đó là /var/lib/private/oleafly-server.
Để giữ client secret ra khỏi tệp cài đặt, hãy dùng một credential của systemd. Lưu secret trong /etc/oleafly-server/github-client-secret với chế độ 600, xóa dòng OLEAFLY_GITHUB_CLIENT_SECRET khỏi tệp cài đặt, chạy sudo systemctl edit oleafly-server, và thêm:
[Service]LoadCredential=github-client-secret:/etc/oleafly-server/github-client-secretEnvironment=OLEAFLY_GITHUB_CLIENT_SECRET_FILE=%d/github-client-secretRồi chạy sudo systemctl restart oleafly-server.
Đặt HTTPS đứng trước
Phần tiêu đề “Đặt HTTPS đứng trước”Cài Caddy theo hướng dẫn dành cho bản phân phối của bạn (mở trong thẻ mới). Thay /etc/caddy/Caddyfile bằng các dòng sau và chạy sudo systemctl reload caddy. Caddy lấy chứng chỉ và chuyển tiếp các kết nối thời gian thực.
collab.example.org { reverse_proxy 127.0.0.1:8080}Với nginx hoặc Apache, hoặc một máy chủ web mà trường đại học của bạn đã chạy, hãy đọc Sau một reverse proxy.
Khi không có địa chỉ công khai
Phần tiêu đề “Khi không có địa chỉ công khai”Nếu máy không có địa chỉ công khai, chẳng hạn một máy tính trong phòng thí nghiệm của bạn nằm sau tường lửa của trường đại học, Cloudflare Tunnel có thể làm cho nó truy cập được. Bạn cần một tài khoản Cloudflare có tên miền của bạn trên đó. Cloudflare xử lý HTTPS cho tên máy chủ, nên các yêu cầu được giải mã trên mạng của Cloudflare trước khi đến máy của bạn. Hãy kể Cloudflare vào số những bên có thể đọc lưu lượng đến máy chủ của bạn.
-
Làm theo các bước của Docker Compose thủ công cho đến bước chỉnh sửa
.env. ĐặtOLEAFLY_DOMAINthành tên máy chủ bạn sẽ dùng, chẳng hạncollab.example.org. Trình cài đặt một lệnh không phù hợp ở đây, vì nó khởi động Caddy. -
Chỉ khởi động máy chủ. Caddy không cần ở đây:
Cửa sổ terminal sudo docker compose up -d oleafly-server -
Trong bảng điều khiển Cloudflare, vào Networking › Tunnels, chọn Create Tunnel, đặt tên cho tunnel, rồi chọn Create Tunnel lần nữa. Sao chép token từ lệnh cài đặt mà nó hiển thị.
-
Khởi động tunnel cạnh máy chủ. Lệnh
readchờ bạn dán token vào và không hiển thị token:Cửa sổ terminal 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 -
Quay lại bảng điều khiển, mở tunnel. Dưới Routes, chọn Add route, rồi Published application. Dưới Hostname, nhập tên miền phụ và chọn tên miền của bạn. Đặt Service URL thành
http://oleafly-server:8080và chọn Add route. -
Kiểm tra rằng nó trả lời tại
https://collab.example.org/healthz, rồi trở thành quản trị viên đầu tiên.
Trên một máy không có Docker, hãy cài cloudflared từ kho gói của Cloudflare (mở trong thẻ mới), chạy sudo cloudflared service install theo sau là token, và đặt Service URL thành http://127.0.0.1:8080.
Cloudflare chuyển tiếp các kết nối thời gian thực và đặt địa chỉ của người truy cập ở vị trí cuối cùng trong X-Forwarded-For, nên hãy giữ OLEAFLY_BEHIND_PROXY=true. Khi tunnel dẫn đến một proxy khác, chẳng hạn proxy của Coolify, chứ không đi thẳng đến máy chủ, cũng hãy đặt OLEAFLY_PROXY_HOPS=2. Cloudflare từ chối các yêu cầu lớn hơn 100 MB trên các gói Free và Pro, nên hãy đặt OLEAFLY_MAX_PROJECT_MB thành 100 hoặc nhỏ hơn, nếu không các dự án lớn sẽ không tải lên được. Đừng đặt Cloudflare Access đứng trước máy chủ, vì Oleafly không thể vượt qua trang đăng nhập của nó.
Khi bạn cập nhật máy chủ về sau, hãy tải các tệp của bản phát hành mới và nêu tên dịch vụ để Caddy không tham gia: sudo docker compose up -d oleafly-server.
Trở thành quản trị viên đầu tiên
Phần tiêu đề “Trở thành quản trị viên đầu tiên”Một máy chủ mới chưa có quản trị viên. Cho đến khi ai đó hoàn tất thiết lập, máy chủ tạo một mã thiết lập dùng một lần mới mỗi lần khởi động và ghi nó vào nhật ký.
- Tìm dòng mới nhất bắt đầu bằng
Setup code:trong nhật ký:- Cài đặt bằng một lệnh: trình cài đặt in mã khi hoàn tất. Để xem lại, chạy
cd /opt/oleafly-server && sudo docker compose logs oleafly-server | grep 'Setup code' - Docker Compose thủ công: chạy
sudo docker compose logs oleafly-server | grep 'Setup code'trong thư mục của máy chủ - Coolify: nhật ký của dịch vụ
oleafly-server - systemd:
sudo journalctl -u oleafly-server | grep 'Setup code'
- Cài đặt bằng một lệnh: trình cài đặt in mã khi hoàn tất. Để xem lại, chạy
- Trong Oleafly, mở Settings → Collaboration, chọn Add server, và nhập địa chỉ máy chủ của bạn. Oleafly nhận thấy máy chủ cần thiết lập và hỏi Setup code.
- Nhập mã và đăng nhập bằng bất kỳ nhà cung cấp nào bạn đã cấu hình. Bạn trở thành quản trị viên của máy chủ, và mã ngừng hoạt động.
Bất kỳ ai có mã trước khi bạn dùng nó đều có thể tự lên làm quản trị viên, nên hãy chỉ dán mã vào Oleafly mà thôi.
Bạn cũng có thể tự chọn mã bằng OLEAFLY_SETUP_CODE: ít nhất 12 chữ cái hoặc chữ số, thêm dấu gạch ngang hay dấu cách tùy ý. Máy chủ khi đó không bao giờ in mã ra. Nhật ký chỉ ghi Setup code: set by OLEAFLY_SETUP_CODE, và bạn nhập giá trị bạn đã đặt. Sau khi thiết lập xong, hãy xóa nó khỏi cài đặt của bạn.
Tiếp theo, hãy cho mọi người vào. Đăng nhập và truy cập giải thích cách làm.
Kiểm tra máy chủ
Phần tiêu đề “Kiểm tra máy chủ”- Với cách cài đặt bằng một lệnh,
sudo sh /opt/oleafly-server/install.sh statuskiểm tra các container và HTTPS trong một lần. https://collab.example.org/healthztrả lời200khi tiến trình máy chủ đang chạy./readyzchỉ trả lời200khi máy chủ ghi được vào cơ sở dữ liệu và thư mục dữ liệu của mình. Khi không ghi được, chẳng hạn khi đĩa đầy, nó trả lời503và nêu rõ bộ phận gặp lỗi,databasehoặcstorage.- Image Docker tự kiểm tra
/readyz, nêndocker psvà Coolify hiển thị một máy chủ không ổn định thay vì một máy chủ đang chạy mà không lưu được gì. - Trong Oleafly, Test connection dưới Settings → Collaboration kiểm tra địa chỉ, HTTPS, phiên bản, các kết nối thời gian thực, các tùy chọn đăng nhập và đồng hồ của máy chủ. Connection checks trong bảng điều khiển quản trị chạy cũng những kiểm tra đó.