help: Add proper documentation of Zulip import/export process.

Based on an original version written by Rishi, but this has been
basically rewritten by tabbott.

We also clean up one confusing part of our Slack docs.

templates/zerver/faq.html

@@ -73,8 +73,10 @@
                     Can I start on Zulip Cloud and later move to On-Premise?
                 </div>
                 <p class="answer">
-                    Yes! Our high quality export and import tools ensure you
-                    can always move from our hosting to yours (and back). If
+                    Yes! Our high
+                    quality <a href="/help/import-or-export-a-zulip-organization">export
+                    and import tools</a> ensure you can always move
+                    from our hosting to yours (and back). If
                     you&rsquo;d like to do a migration, email
                     support@zulipchat.com and we'll get you started!
                 </p>

templates/zerver/help/import-data-from-slack.md

@@ -30,8 +30,9 @@ First, you need to do some things in Slack to setup the export:
     using [upgrade-zulip-from-git][upgrade-zulip-from-git] to avoid
     bugs in the earliest versions of the Slack import tool.
 
-Log in to your Zulip server as the `zulip` user. Run the following
-commands, replacing `<token>` with the value generated above:
+Log in to a shell on your Zulip server as the `zulip` user. Run the
+following commands, replacing `<token>` with the value generated
+above:
 
 ```
 cd /home/zulip/deployments/current

templates/zerver/help/import-or-export-a-zulip-organization.md

@@ -0,0 +1,102 @@
+# Import or export a Zulip organization
+
+Zulip has high quality export and import tools that can be used to
+migrate from the hosted Zulip Cloud service to or from your own
+servers, move data from one Zulip server to another, do backups or
+compliance work, etc.
+
+The import half of these tools also powers our
+[Slack import feature](/help/import-data-from-slack).
+
+!!! warn ""
+    These instructions currently require shell access to the Zulip
+    server. If you'd like to migrate to or from the Zulip Cloud
+    service hosted on zulipchat.com, contact support@zulipchat.com.
+
+When using these tools, it's important to ensure that the Zulip server
+you're exporting from and the one you're exporting to are running the
+same version of Zulip (since we do change and extend the format from
+time to time).
+
+### Export your Zulip data
+
+For best results, you'll want to shut down access to the organization
+you are exporting with `manage.py deactivate_realm` before exporting,
+so that nobody can send new messages (etc.) while you're exporting
+data.  We include that in the instructions below.
+
+Log in to a shell on your Zulip server as the `zulip` user. Run the
+following commands:
+
+```
+cd /home/zulip/deployments/current
+./manage deactivate_realm -r ''  # Deactivates the organization
+./manage.py export -r ''  # Exports the data
+```
+
+(The `-r` option lets you specify the organization to export; `''` is
+the default organization hosted at the Zulip server's root domain.)
+
+This will generate a tarred archive with a name like
+`/tmp/zulip-export-zcmpxfm6.tar.gz`.  The archive contains several
+JSON files (containing the Zulip organization's data) as well as an
+archive of all the organization's uploaded files.
+
+### Import into a new Zulip server
+
+Log in to a shell on your Zulip server as the `zulip` user. Run the
+following commands, replacing the filename with the path to your data
+export tarball:
+
+```
+cd /tmp
+tar -xf /path/to/export/file/zulip-export-zcmpxfm6.tar.gz
+cd /home/zulip/deployments/current
+./manage.py import --destroy-rebuild-database '' /tmp/zulip-export-zcmpxfm6
+./manage reactivate_realm -r ''  # Reactivates the organization
+```
+
+!!! warn ""
+    **Warning:** This will destroy all existing data in your Zulip server
+
+### Import into an existing Zulip server
+
+If you already have some organizations hosted a your Zulip server, and
+want to add import an additional Zulip organization, you can use the
+following procedure.
+
+Log in to your Zulip server as the `zulip` user. Run the following
+commands, replacing the filename with the path to your data export
+tarball, `<subdomain>` with the subdomain of the URL you'd like for
+your imported Zulip organization.
+
+```
+cd /tmp
+tar -xf /path/to/export/file/zulip-export-zcmpxfm6.tar.gz
+cd /home/zulip/deployments/current
+./manage.py import --import-into-nonempty <subdomain> /tmp/zulip-export-zcmpxfm6
+./manage reactivate_realm -r ''  # Reactivates the organization
+```
+
+## Logging in
+
+Once the import completes, all your users will have accounts in your
+new Zulip organization, but those accounts won't have passwords yet
+(since for very good security reasons, passwords are not exported).
+Your users will need to either authenticate using something like
+Google auth, or start by resetting their passwords.
+
+You can use the `./manage.py send_password_reset_email` command to
+send password reset emails to your users.  We
+recommend starting with sending one to yourself for testing:
+
+```
+./manage.py send_password_reset_email -u username@example.com
+```
+
+and then once you're ready, you can email them to everyone using e.g.
+```
+./manage.py send_password_reset_email -r '' --all-users
+```
+
+(replace `''` with your subdomain if you're using one).

templates/zerver/help/include/sidebar.md

@@ -116,6 +116,7 @@
 * [Update your organization's settings](/help/change-your-organization-settings)
 * [Link to your Zulip from the web](/help/join-zulip-chat-badge)
 * [Import data from Slack](/help/import-data-from-slack)
+* [Import or export a Zulip organization](/help/import-or-export-a-zulip-organization)
 * [Restrict new users by email domain](/help/restrict-user-email-addresses-to-certain-domains)
 * [Allow joining without an invitation](/help/allow-anyone-to-join-without-an-invitation)
 * [Manage who can send invitations](/help/only-allow-admins-to-invite-new-users)