1# Local Collaboration
2
31. Ensure you have access to our cloud infrastructure. If you don't have access, you can't collaborate locally at this time.
4
52. Make sure you've installed Zed's dependencies for your platform:
6
7- [macOS](#macos)
8- [Linux](#linux)
9- [Windows](#backend-windows)
10
11Note that `collab` can be compiled only with MSVC toolchain on Windows
12
133. Clone down our cloud repository and follow the instructions in the cloud README
14
154. Setup the local database for your platform:
16
17- [macOS & Linux](#database-unix)
18- [Windows](#database-windows)
19
205. Run collab:
21
22- [macOS & Linux](#run-collab-unix)
23- [Windows](#run-collab-windows)
24
25## Backend Dependencies
26
27If you are developing collaborative features of Zed, you'll need to install the dependencies of zed's `collab` server:
28
29- PostgreSQL
30- LiveKit
31- Foreman
32
33You can install these dependencies natively or run them under Docker.
34
35### macOS
36
371. Install [Postgres.app](https://postgresapp.com) or [postgresql via homebrew](https://formulae.brew.sh/formula/postgresql@15):
38
39 ```sh
40 brew install postgresql@15
41 ```
42
432. Install [Livekit](https://formulae.brew.sh/formula/livekit) and [Foreman](https://formulae.brew.sh/formula/foreman)
44
45 ```sh
46 brew install livekit foreman
47 ```
48
49- 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
50
51Alternatively, if you have [Docker](https://www.docker.com/) installed you can bring up all the `collab` dependencies using Docker Compose.
52
53### Linux
54
551. Install [Postgres](https://www.postgresql.org/download/linux/)
56
57 ```sh
58 sudo apt-get install postgresql # Ubuntu/Debian
59 sudo pacman -S postgresql # Arch Linux
60 sudo dnf install postgresql postgresql-server # RHEL/Fedora
61 sudo zypper install postgresql postgresql-server # OpenSUSE
62 ```
63
642. Install [Livekit](https://github.com/livekit/livekit-cli)
65
66 ```sh
67 curl -sSL https://get.livekit.io/cli | bash
68 ```
69
703. Install [Foreman](https://theforeman.org/manuals/3.15/quickstart_guide.html)
71
72### Windows {#backend-windows}
73
74> This section is still in development. The instructions are not yet complete.
75
76- Install [Postgres](https://www.postgresql.org/download/windows/)
77- Install [Livekit](https://github.com/livekit/livekit), optionally you can add the `livekit-server` binary to your `PATH`.
78
79Alternatively, if you have [Docker](https://www.docker.com/) installed you can bring up all the `collab` dependencies using Docker Compose.
80
81### Docker {#Docker}
82
83If you have docker or podman available, you can run the backend dependencies inside containers with Docker Compose:
84
85```sh
86docker compose up -d
87```
88
89## Database setup
90
91Before you can run the `collab` server locally, you'll need to set up a `zed` Postgres database.
92
93### On macOS and Linux {#database-unix}
94
95```sh
96script/bootstrap
97```
98
99This 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.
100
101The script will seed the database with various content defined by:
102
103```sh
104cat crates/collab/seed.default.json
105```
106
107To 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.
108
109```json [settings]
110{
111 "admins": ["admin1", "admin2"],
112 "channels": ["zed"]
113}
114```
115
116### On Windows {#database-windows}
117
118```powershell
119.\script\bootstrap.ps1
120```
121
122## Testing collaborative features locally
123
124### On macOS and Linux {#run-collab-unix}
125
126Ensure that Postgres is configured and running, then run Zed's collaboration server and the `livekit` dev server:
127
128```sh
129foreman start
130# OR
131docker compose up
132```
133
134Alternatively, if you're not testing voice and screenshare, you can just run `collab` and `cloud`, and not the `livekit` dev server:
135
136```sh
137cargo run -p collab -- serve all
138```
139
140```sh
141cd ../cloud; cargo make dev
142```
143
144In a new terminal, run two or more instances of Zed.
145
146```sh
147script/zed-local -3
148```
149
150This 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`.
151
152### On Windows {#run-collab-windows}
153
154Since `foreman` is not available on Windows, you can run the following commands in separate terminals:
155
156```powershell
157cargo run --package=collab -- serve all
158```
159
160If you have added the `livekit-server` binary to your `PATH`, you can run:
161
162```powershell
163livekit-server --dev
164```
165
166Otherwise,
167
168```powershell
169.\path\to\livekit-serve.exe --dev
170```
171
172You'll also need to start the cloud server:
173
174```powershell
175cd ..\cloud; cargo make dev
176```
177
178In a new terminal, run two or more instances of Zed.
179
180```powershell
181node .\script\zed-local -2
182```
183
184Note that this requires `node.exe` to be in your `PATH`.
185
186## Running a local collab server
187
188> [!NOTE]
189> Because of recent changes to our authentication system, Zed will not be able to authenticate itself with, and therefore use, a local collab server.
190
191If 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 support for authentication nor extensions.
192
193Configuration 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.
194
195By 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`.
196
197To 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.
198
199```json [settings]
200{
201 "admins": ["nathansobo"]
202}
203```
204
205By 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`
206
207Then 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)