Skip to content

Commit 16ed345

Browse files
alexmvalexmv
committed
UPGRADING: Split out of README.md.
1 parent 3ec2386 commit 16ed345

File tree

2 files changed

+190
-186
lines changed

2 files changed

+190
-186
lines changed

‎README.md

Lines changed: 5 additions & 186 deletions
Original file line numberDiff line numberDiff line change
@@ -298,6 +298,11 @@ to `/etc/ssl/certs/ca-certificates.crt`.
298298

299299
At this point you are ready to build Zulip.
300300

301+
### Upgrading
302+
303+
See the [separate upgrading document](UPGRADING.md) for upgrading
304+
instructions.
305+
301306
## Running a Zulip server with Kubernetes
302307

303308
A Kubernetes pod file is in the `kubernetes/` folder; you can run it
@@ -351,192 +356,6 @@ is behind a load balancer and you need the Zulip server to respond
351356
over HTTP, you can configure that via setting `DISABLE_HTTPS: "True"`
352357
in the Docker environment (`docker-compose.yml`).
353358

354-
## Upgrading the Zulip container
355-
356-
You can upgrade your Zulip installation to any newer version of Zulip
357-
with the following instructions. At a high level, the strategy is to
358-
download a new image, stop the `zulip` container, and then boot it
359-
back up with the new image. When the upgraded `zulip` container boots
360-
the first time, it will run the necessary database migrations with
361-
`manage.py migrate`.
362-
363-
If you ever find you need to downgrade your Zulip server, you'll need
364-
to use `manage.py migrate` to downgrade the database schema manually.
365-
366-
If you are using old `galexrt/docker-zulip` images (from Zulip 1.8.1 or
367-
older), you need to upgrade the postgres image from
368-
`quay.io/galexrt/postgres-zulip-tsearchextras:latest`. Refer to the
369-
[instructions for upgrading from the old galexrt/docker-zulip](#upgrading-from-the-old-galexrtdocker-zulip)
370-
section.
371-
372-
### Using `docker-compose`
373-
374-
0. (Optional) Upgrading does not delete your data, but it's generally
375-
good practice to
376-
[back up your Zulip data](http://zulip.readthedocs.io/en/latest/prod-maintain-secure-upgrade.html#backups)
377-
before upgrading to make switching back to the old version
378-
simple. You can find your docker data volumes by looking at the
379-
`volumes` lines in `docker-compose.yml`
380-
e.g. `/opt/docker/zulip/postgresql/data/`.
381-
382-
Note that `docker-zulip` did not support for Zulip's built-in
383-
`restore-backup` tool before Zulip 3.0.
384-
385-
1. Pull the new image version, e.g. for `2.0.8` run: `docker pull zulip/docker-zulip:2.0.8-0`. We recommend always upgrading to the
386-
latest minor release within a major release series.
387-
388-
2. Update this project to the corresponding `docker-zulip` version and
389-
resolve any merge conflicts in `docker-compose.yml`.
390-
This is important as new Zulip releases may require additional
391-
settings to be specified in `docker-compose.yml`
392-
(E.g. authentication settings for `memcached` became mandatory in
393-
the `2.1.2` release).
394-
395-
**Note:** Do not make any changes to the database version or
396-
volume. If there is a difference in database version, leave those
397-
unchanged for now, and complete that upgrade separately after the
398-
Zulip upgrade; see [the section below][pg-upgrade].
399-
400-
[pg-upgrade]: #upgrading-zulipzulip-postgresql-to-14
401-
402-
3. Verify that your updated `docker-compose.yml` points to the desired image version,
403-
e.g.:
404-
405-
```yml
406-
zulip:
407-
image: "zulip/docker-zulip:2.0.1-0"
408-
```
409-
410-
4. You can execute the upgrade by running:
411-
412-
```
413-
# Stops the old zulip container; this begins your downtime
414-
docker-compose stop
415-
# Boots the new zulip container; this ends your downtime
416-
docker-compose up
417-
# Deletes the old container images
418-
docker-compose rm
419-
```
420-
421-
That's it! Zulip is now running the updated version.
422-
You can confirm you're running the latest version by running:
423-
424-
```bash
425-
docker-compose exec -u zulip zulip cat /home/zulip/deployments/current/version.py
426-
```
427-
428-
### Upgrading from a Git repository
429-
430-
1. Edit `docker-compose.yml` to comment out the `image` line, and
431-
specify the Git commit you'd like to build the zulip container from.
432-
E.g.:
433-
434-
```
435-
zulip:
436-
# image: "zulip/docker-zulip:2.0.1-0"
437-
build:
438-
context: .
439-
args:
440-
# Change these if you want to build zulip from a different repo/branch
441-
ZULIP_GIT_URL: https://github.com/zulip/zulip.git
442-
ZULIP_GIT_REF: master
443-
```
444-
445-
You can set `ZULIP_GIT_URL` to any clone of the zulip/zulip git
446-
repository, and `ZULIP_GIT_REF` to be any ref name in that repository
447-
(e.g. `master` or `1.9.0` or
448-
`445932cc8613c77ced023125248c8b966b3b7528`).
449-
450-
2. Run `docker-compose build zulip` to build a Zulip Docker image from
451-
the specified Git version.
452-
453-
Then stop and restart the container as described in the previous section.
454-
455-
### Upgrading zulip/zulip-postgresql to 14
456-
457-
The Docker Compose configuration for version 6.0-0 and higher default
458-
to using PostgreSQL 14, as the previously-used PostgreSQL 10 is no
459-
longer supported. Because the data is specific to the version of
460-
PostgreSQL which is running, it must be dumped and re-loaded into a
461-
new volume to upgrade. PostgreSQL 14 will refuse to start if provided
462-
with un-migrated data from PostgreSQL 10.
463-
464-
The provided `upgrade-postgresql` tool will dump the contents of the
465-
`postgresql` image's volume, create a new PostgreSQL 14 volume,
466-
perform the necessary migration, update the `docker-compose.yml`
467-
file to match, and re-start Zulip.
468-
469-
### Upgrading from the old galexrt/docker-zulip
470-
471-
If you are using an earlier version of `galexrt/docker-zulip` which
472-
used the `quay.io/galexrt/postgres-zulip-tsearchextras:latest`
473-
Postgres image, you need to run a few manual steps to upgrade to the
474-
`zulip/zulip-postgresql` Postgres image (because we've significantly
475-
upgraded the major postgres version).
476-
477-
These instructions assume that you have not changed the default
478-
Postgres data path (`/opt/docker/zulip/postgresql/data`) in your
479-
`docker-compose.yml`. If you have changed it, please replace all
480-
occurences of `/opt/docker/zulip/postgresql/data` with your path.
481-
482-
1. Make a backup of your Zulip Postgres data dir.
483-
484-
2. Stop all Zulip containers, except the postgres one (e.g. use
485-
`docker stop` and not `docker-compose stop`).
486-
487-
3. Create a new (upgraded) Postgres container using a different data directory:
488-
489-
```
490-
docker run -d \
491-
--name postgresnew \
492-
-e POSTGRES_DB=zulip \
493-
-e POSTGRES_USER=zulip \
494-
-e POSTGRES_PASSWORD=zulip \
495-
-v /opt/docker/zulip/postgresql/new:/var/lib/postgresql/data:rw \
496-
zulip/zulip-postgresql:latest
497-
```
498-
499-
4. Use `pg_dumpall` to dump all data from the existing Postgres container to
500-
the new Postgres container:
501-
502-
```
503-
docker-compose exec database pg_dumpall -U postgres | \
504-
docker exec -i postgresnew psql -U postgres
505-
```
506-
507-
5. Stop and remove both Postgres containers:
508-
509-
```
510-
docker-compose rm --stop database
511-
docker rm --stop postgresnew
512-
```
513-
514-
6. Edit your `docker-compose.yml` to use the
515-
`zulip/zulip-postgresql:latest` image for the `database` container
516-
(this is the default in `zulip/docker-zulip`).
517-
518-
7. Replace the old Postgres data directory with upgraded data directory:
519-
520-
```
521-
mv /opt/docker/zulip/postgresql/data /opt/docker/zulip/postgresql/old
522-
mv /opt/docker/zulip/postgresql/new /opt/docker/zulip/postgresql/data
523-
```
524-
525-
8. Delete the old existing containers:
526-
527-
```
528-
docker-compose rm
529-
```
530-
531-
9. Start Zulip up again:
532-
533-
```
534-
docker-compose up
535-
```
536-
537-
That should be it. Your Postgres data has now been updated to use the
538-
`zulip/zulip-postgresql` image.
539-
540359
## Troubleshooting
541360

542361
Common issues include:

‎UPGRADING.md

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
## Upgrading the Zulip container
2+
3+
You can upgrade your Zulip installation to any newer version of Zulip
4+
with the following instructions. At a high level, the strategy is to
5+
download a new image, stop the `zulip` container, and then boot it
6+
back up with the new image. When the upgraded `zulip` container boots
7+
the first time, it will run the necessary database migrations with
8+
`manage.py migrate`.
9+
10+
If you ever find you need to downgrade your Zulip server, you'll need
11+
to use `manage.py migrate` to downgrade the database schema manually.
12+
13+
If you are using old `galexrt/docker-zulip` images (from Zulip 1.8.1 or
14+
older), you need to upgrade the postgres image from
15+
`quay.io/galexrt/postgres-zulip-tsearchextras:latest`. Refer to the
16+
[instructions for upgrading from the old galexrt/docker-zulip](#upgrading-from-the-old-galexrtdocker-zulip)
17+
section.
18+
19+
### Using `docker-compose`
20+
21+
0. (Optional) Upgrading does not delete your data, but it's generally
22+
good practice to
23+
[back up your Zulip data](http://zulip.readthedocs.io/en/latest/prod-maintain-secure-upgrade.html#backups)
24+
before upgrading to make switching back to the old version
25+
simple. You can find your docker data volumes by looking at the
26+
`volumes` lines in `docker-compose.yml`
27+
e.g. `/opt/docker/zulip/postgresql/data/`.
28+
29+
Note that `docker-zulip` did not support for Zulip's built-in
30+
`restore-backup` tool before Zulip 3.0.
31+
32+
1. Pull the new image version, e.g. for `2.0.8` run: `docker pull zulip/docker-zulip:2.0.8-0`. We recommend always upgrading to the
33+
latest minor release within a major release series.
34+
35+
2. Update this project to the corresponding `docker-zulip` version and
36+
resolve any merge conflicts in `docker-compose.yml`.
37+
This is important as new Zulip releases may require additional
38+
settings to be specified in `docker-compose.yml`
39+
(E.g. authentication settings for `memcached` became mandatory in
40+
the `2.1.2` release).
41+
42+
**Note:** Do not make any changes to the database version or
43+
volume. If there is a difference in database version, leave those
44+
unchanged for now, and complete that upgrade separately after the
45+
Zulip upgrade; see [the section below][pg-upgrade].
46+
47+
[pg-upgrade]: #upgrading-zulipzulip-postgresql-to-14
48+
49+
3. Verify that your updated `docker-compose.yml` points to the desired image version,
50+
e.g.:
51+
52+
```yml
53+
zulip:
54+
image: "zulip/docker-zulip:2.0.1-0"
55+
```
56+
57+
4. You can execute the upgrade by running:
58+
59+
```
60+
# Stops the old zulip container; this begins your downtime
61+
docker-compose stop
62+
# Boots the new zulip container; this ends your downtime
63+
docker-compose up
64+
# Deletes the old container images
65+
docker-compose rm
66+
```
67+
68+
That's it! Zulip is now running the updated version.
69+
You can confirm you're running the latest version by running:
70+
71+
```bash
72+
docker-compose exec -u zulip zulip cat /home/zulip/deployments/current/version.py
73+
```
74+
75+
### Upgrading from a Git repository
76+
77+
1. Edit `docker-compose.yml` to comment out the `image` line, and
78+
specify the Git commit you'd like to build the zulip container from.
79+
E.g.:
80+
81+
```
82+
zulip:
83+
# image: "zulip/docker-zulip:2.0.1-0"
84+
build:
85+
context: .
86+
args:
87+
# Change these if you want to build zulip from a different repo/branch
88+
ZULIP_GIT_URL: https://github.com/zulip/zulip.git
89+
ZULIP_GIT_REF: master
90+
```
91+
92+
You can set `ZULIP_GIT_URL` to any clone of the zulip/zulip git
93+
repository, and `ZULIP_GIT_REF` to be any ref name in that repository
94+
(e.g. `master` or `1.9.0` or
95+
`445932cc8613c77ced023125248c8b966b3b7528`).
96+
97+
2. Run `docker-compose build zulip` to build a Zulip Docker image from
98+
the specified Git version.
99+
100+
Then stop and restart the container as described in the previous section.
101+
102+
### Upgrading zulip/zulip-postgresql to 14
103+
104+
The Docker Compose configuration for version 6.0-0 and higher default
105+
to using PostgreSQL 14, as the previously-used PostgreSQL 10 is no
106+
longer supported. Because the data is specific to the version of
107+
PostgreSQL which is running, it must be dumped and re-loaded into a
108+
new volume to upgrade. PostgreSQL 14 will refuse to start if provided
109+
with un-migrated data from PostgreSQL 10.
110+
111+
The provided `upgrade-postgresql` tool will dump the contents of the
112+
`postgresql` image's volume, create a new PostgreSQL 14 volume,
113+
perform the necessary migration, update the `docker-compose.yml`
114+
file to match, and re-start Zulip.
115+
116+
### Upgrading from the old galexrt/docker-zulip
117+
118+
If you are using an earlier version of `galexrt/docker-zulip` which
119+
used the `quay.io/galexrt/postgres-zulip-tsearchextras:latest`
120+
Postgres image, you need to run a few manual steps to upgrade to the
121+
`zulip/zulip-postgresql` Postgres image (because we've significantly
122+
upgraded the major postgres version).
123+
124+
These instructions assume that you have not changed the default
125+
Postgres data path (`/opt/docker/zulip/postgresql/data`) in your
126+
`docker-compose.yml`. If you have changed it, please replace all
127+
occurences of `/opt/docker/zulip/postgresql/data` with your path.
128+
129+
1. Make a backup of your Zulip Postgres data dir.
130+
131+
2. Stop all Zulip containers, except the postgres one (e.g. use
132+
`docker stop` and not `docker-compose stop`).
133+
134+
3. Create a new (upgraded) Postgres container using a different data directory:
135+
136+
```
137+
docker run -d \
138+
--name postgresnew \
139+
-e POSTGRES_DB=zulip \
140+
-e POSTGRES_USER=zulip \
141+
-e POSTGRES_PASSWORD=zulip \
142+
-v /opt/docker/zulip/postgresql/new:/var/lib/postgresql/data:rw \
143+
zulip/zulip-postgresql:latest
144+
```
145+
146+
4. Use `pg_dumpall` to dump all data from the existing Postgres container to
147+
the new Postgres container:
148+
149+
```
150+
docker-compose exec database pg_dumpall -U postgres | \
151+
docker exec -i postgresnew psql -U postgres
152+
```
153+
154+
5. Stop and remove both Postgres containers:
155+
156+
```
157+
docker-compose rm --stop database
158+
docker rm --stop postgresnew
159+
```
160+
161+
6. Edit your `docker-compose.yml` to use the
162+
`zulip/zulip-postgresql:latest` image for the `database` container
163+
(this is the default in `zulip/docker-zulip`).
164+
165+
7. Replace the old Postgres data directory with upgraded data directory:
166+
167+
```
168+
mv /opt/docker/zulip/postgresql/data /opt/docker/zulip/postgresql/old
169+
mv /opt/docker/zulip/postgresql/new /opt/docker/zulip/postgresql/data
170+
```
171+
172+
8. Delete the old existing containers:
173+
174+
```
175+
docker-compose rm
176+
```
177+
178+
9. Start Zulip up again:
179+
180+
```
181+
docker-compose up
182+
```
183+
184+
That should be it. Your Postgres data has now been updated to use the
185+
`zulip/zulip-postgresql` image.

0 commit comments

Comments
 (0)