1# Local Collaboration
2
3First, make sure you've installed Zed's dependencies for your platform:
4
5- [macOS](./macos.md#backend-dependencies)
6- [Linux](./linux.md#backend-dependencies)
7- [Windows](./windows.md#backend-dependencies)
8
9Note that `collab` can be compiled only with MSVC toolchain on Windows
10
11## Backend Dependencies
12
13If you are developing collaborative features of Zed, you'll need to install the dependencies of zed's `collab` server:
14
15- PostgreSQL
16- LiveKit
17- Foreman
18
19You can install these dependencies natively or run them under Docker.
20
21### MacOS
22
231. Install [Postgres.app](https://postgresapp.com) or [postgresql via homebrew](https://formulae.brew.sh/formula/postgresql@15):
24
25 ```sh
26 brew install postgresql@15
27 ```
28
292. Install [Livekit](https://formulae.brew.sh/formula/livekit) and [Foreman](https://formulae.brew.sh/formula/foreman)
30
31 ```sh
32 brew install livekit foreman
33 ```
34
35- Follow the steps in the [collab README](https://github.com/zed-industries/zed/blob/main/crates/collab/README.md) to configure the Postgres database for integration tests
36
37Alternatively, if you have [Docker](https://www.docker.com/) installed you can bring up all the `collab` dependencies using Docker Compose:
38
39### Linux
40
411. Install [Postgres](https://www.postgresql.org/download/linux/)
42
43 ```sh
44 sudo apt-get install postgresql postgresql # Ubuntu/Debian
45 sudo pacman -S postgresql # Arch Linux
46 sudo dnf install postgresql postgresql-server # RHEL/Fedora
47 sudo zypper install postgresql postgresql-server # OpenSUSE
48 ```
49
502. Install [Livekit](https://github.com/livekit/livekit-cli)
51
52 ```sh
53 curl -sSL https://get.livekit.io/cli | bash
54 ```
55
563. Install [Foreman](https://theforeman.org/manuals/3.15/quickstart_guide.html)
57
58### Windows {#backend-windows}
59
60> This section is still in development. The instructions are not yet complete.
61
62- Install [Postgres](https://www.postgresql.org/download/windows/)
63- Install [Livekit](https://github.com/livekit/livekit), optionally you can add the `livekit-server` binary to your `PATH`.
64
65Alternatively, if you have [Docker](https://www.docker.com/) installed you can bring up all the `collab` dependencies using Docker Compose.
66
67### Docker {#Docker}
68
69If you have docker or podman available, you can run the backend dependencies inside containers with Docker Compose:
70
71```sh
72docker compose up -d
73```
74
75## Database setup
76
77Before you can run the `collab` server locally, you'll need to set up a `zed` Postgres database.
78
79### On macOS and Linux
80
81```sh
82script/bootstrap
83```
84
85This script will set up the `zed` Postgres database, and populate it with some users. It requires internet access, because it fetches some users from the GitHub API.
86
87The script will seed the database with various content defined by:
88
89```sh
90cat crates/collab/seed.default.json
91```
92
93To use a different set of admin users, you can create your own version of that json file and export the `SEED_PATH` environment variable. Note that the usernames listed in the admins list currently must correspond to valid GitHub users.
94
95```json
96{
97 "admins": ["admin1", "admin2"],
98 "channels": ["zed"]
99}
100```
101
102### On Windows
103
104```powershell
105.\script\bootstrap.ps1
106```
107
108## Testing collaborative features locally
109
110### On macOS and Linux
111
112Ensure that Postgres is configured and running, then run Zed's collaboration server and the `livekit` dev server:
113
114```sh
115foreman start
116# OR
117docker compose up
118```
119
120Alternatively, if you're not testing voice and screenshare, you can just run `collab`, and not the `livekit` dev server:
121
122```sh
123cargo run -p collab -- serve all
124```
125
126In a new terminal, run two or more instances of Zed.
127
128```sh
129script/zed-local -3
130```
131
132This script starts one to four instances of Zed, depending on the `-2`, `-3` or `-4` flags. Each instance will be connected to the local `collab` server, signed in as a different user from `.admins.json` or `.admins.default.json`.
133
134### On Windows
135
136Since `foreman` is not available on Windows, you can run the following commands in separate terminals:
137
138```powershell
139cargo run --package=collab -- serve all
140```
141
142If you have added the `livekit-server` binary to your `PATH`, you can run:
143
144```powershell
145livekit-server --dev
146```
147
148Otherwise,
149
150```powershell
151.\path\to\livekit-serve.exe --dev
152```
153
154In a new terminal, run two or more instances of Zed.
155
156```powershell
157node .\script\zed-local -2
158```
159
160Note that this requires `node.exe` to be in your `PATH`.
161
162## Running a local collab server
163
164If you want to run your own version of the zed collaboration service, you can, but note that this is still under development, and there is no good support for authentication nor extensions.
165
166Configuration is done through environment variables. By default it will read the configuration from [`.env.toml`](https://github.com/zed-industries/zed/blob/main/crates/collab/.env.toml) and you should use that as a guide for setting this up.
167
168By default Zed assumes that the DATABASE_URL is a Postgres database, but you can make it use Sqlite by compiling with `--features sqlite` and using a sqlite DATABASE_URL with `?mode=rwc`.
169
170To authenticate you must first configure the server by creating a seed.json file that contains at a minimum your github handle. This will be used to create the user on demand.
171
172```json
173{
174 "admins": ["nathansobo"]
175}
176```
177
178By default the collab server will seed the database when first creating it, but if you want to add more users you can explicitly reseed them with `SEED_PATH=./seed.json cargo run -p collab seed`
179
180Then when running the zed client you must specify two environment variables, `ZED_ADMIN_API_TOKEN` (which should match the value of `API_TOKEN` in .env.toml) and `ZED_IMPERSONATE` (which should match one of the users in your seed.json)