Zulip Documentation Release 1.4.0
Total Page:16
File Type:pdf, Size:1020Kb
Zulip Documentation Release 1.4.0 The Zulip Team Jan 10, 2017 Overview 1 Zulip overview 3 1.1 Community................................................3 1.2 Installing the Zulip Development environment.............................3 1.3 Running Zulip in production.......................................3 1.4 Ways to contribute............................................4 1.5 How to get involved with contributing to Zulip.............................4 1.6 License..................................................5 2 Zulip architectural overview 7 2.1 Key Codebases..............................................7 2.2 Usage assumptions and concepts.....................................7 2.3 Components...............................................8 3 Directory structure 11 3.1 Core Python files............................................. 11 3.2 HTML Templates............................................ 11 3.3 JavaScript and other static assets..................................... 12 3.4 Tests................................................... 12 3.5 Management commands......................................... 12 3.6 Scripts.................................................. 12 3.7 API and Bots............................................... 13 3.8 Production puppet configuration..................................... 13 3.9 Additional Django apps......................................... 13 3.10 Jinja2 Compatibility Files........................................ 13 3.11 Translation files............................................. 13 3.12 Documentation.............................................. 14 4 Zulip 2016 Roadmap 15 4.1 Introduction............................................... 15 4.2 Burning problems............................................ 15 4.3 Core User Experience.......................................... 16 4.4 Ease of setup and onboarding issues................................... 16 4.5 Internationalization............................................ 16 4.6 User Experience at scale......................................... 16 4.7 Administration and management..................................... 17 4.8 Scalability................................................ 17 4.9 Performance............................................... 17 4.10 Technology improvements........................................ 17 i 4.11 Technical Debt.............................................. 18 4.12 Deployment and upgrade process.................................... 18 4.13 Security.................................................. 18 4.14 Testing.................................................. 18 4.15 Development environment........................................ 19 4.16 Documentation.............................................. 19 4.17 Integrations................................................ 19 4.18 Android app............................................... 19 4.19 iOS app.................................................. 20 4.20 Desktop apps............................................... 20 4.21 Community................................................ 20 5 Version History 21 5.1 Unreleased................................................ 21 5.2 1.4.2 - 2016-09-27............................................ 21 5.3 1.4.1 - 2016-09-03............................................ 21 5.4 1.4 - 2016-08-25............................................. 21 5.5 1.3.13 - 2016-06-21........................................... 24 5.6 1.3.12 - 2016-05-10........................................... 25 5.7 1.3.11 - 2016-05-02........................................... 25 5.8 1.3.10 - 2016-01-21........................................... 26 5.9 1.3.9 - 2015-11-16............................................ 26 5.10 1.3.8 - 2015-11-15............................................ 26 5.11 1.3.7 - 2015-10-19............................................ 27 6 Requirements 29 6.1 Server................................................... 29 6.2 Credentials needed............................................ 30 7 Installation 31 7.1 Step 0: Subscribe............................................. 31 7.2 Step 1: Install SSL Certificates...................................... 31 7.3 Step 2: Download and install latest release............................... 31 7.4 Step 3: Configure Zulip......................................... 32 7.5 Step 4: Initialize Zulip database..................................... 32 7.6 Step 5: Create a Zulip organization and login.............................. 32 7.7 Troubleshooting............................................. 33 8 Troubleshooting 35 8.1 Using supervisorctl............................................ 35 8.2 Troubleshooting services......................................... 36 9 Customize Zulip 39 9.1 Integrations................................................ 39 9.2 Streams and Topics............................................ 39 9.3 Notification settings........................................... 40 9.4 Mobile and desktop apps......................................... 40 9.5 All other features............................................. 40 9.6 Enjoy your Zulip installation!...................................... 40 10 Secure, maintain, and upgrade 41 10.1 Upgrading................................................ 41 10.2 Upgrading from a git repository..................................... 43 10.3 Backups................................................. 43 10.4 Monitoring................................................ 44 ii 10.5 Scalability................................................ 45 10.6 Security Model.............................................. 46 10.7 Management commands......................................... 48 11 Authentication methods 51 11.1 Adding additional methods using python-social-auth.......................... 51 11.2 Remote User SSO Authentication.................................... 51 12 Postgres database details 55 12.1 Remote Postgres database........................................ 55 12.2 Debugging postgres database issues................................... 56 12.3 Stopping the Zulip postgres database.................................. 56 12.4 Debugging issues starting postgres.................................... 56 12.5 Postgres Vacuuming alerts........................................ 57 13 Development environment options 59 14 Vagrant environment setup tutorial 61 14.1 Requirements............................................... 61 14.2 Step 1: Install Prerequisites....................................... 62 14.3 Step 2: Get Zulip Code.......................................... 64 14.4 Step 3: Start the dev environment.................................... 64 14.5 Step 4: Developing............................................ 66 14.6 Troubleshooting & Common Errors................................... 68 15 Vagrant environment setup (in brief) 73 15.1 Specifying a proxy............................................ 74 16 Installing directly on Ubuntu 75 17 Installing manually on UNIX 77 17.1 On Debian or Ubuntu systems:...................................... 77 17.2 On Fedora 22 (experimental):...................................... 78 17.3 On CentOS 7 Core (experimental):................................... 79 17.4 On OpenBSD 5.8 (experimental):.................................... 80 17.5 Common to Fedora/CentOS instructions................................. 80 17.6 All Systems:............................................... 81 18 Using Docker (experimental) 83 19 Using the Development Environment 85 20 Writing a new integration 87 20.1 Types of integrations........................................... 87 20.2 General advice.............................................. 88 20.3 Webhook integrations.......................................... 88 20.4 Python script and plugin integrations.................................. 89 20.5 Documenting your integration...................................... 90 20.6 Hello World webhook Walkthrough................................. 90 21 Writing a new application feature 97 21.1 General Process in brief......................................... 97 21.2 Example Feature............................................. 98 22 Writing views in Zulip 103 22.1 What this covers............................................. 103 iii 22.2 What is a view?.............................................. 103 22.3 Modifying urls.py............................................ 103 22.4 Writing human-readable views...................................... 103 22.5 Writing API REST endpoints...................................... 104 22.6 Legacy endpoints used by the web client................................ 108 22.7 Webhook integration endpoints..................................... 108 23 Life of a Request 109 23.1 A request is sent to the server, and handled by Nginx.......................... 109 23.2 Nginx secures traffic with SSL...................................... 109 23.3 Static files are served directly by Nginx................................. 109 23.4 Nginx routes other requests between tornado and django........................ 109 23.5 Django routes the request to a view in urls.py files........................... 110 23.6 Views serving HTML are internationalized by server path....................... 110 23.7 API endpoints use REST......................................... 110 23.8 Django calls rest_dispatch for REST endpoints, and authenticates................... 111 23.9 The view will authorize the user, extract request variables, and validate them............. 112 23.10 Results are given as JSON.......................................