Welcome to the Zulip documentation! — Zulip 10.0-dev+git documentation (original) (raw)
Welcome! Zulip’s documentation is split into four parts:
- Help center documentation, for users and administrators of Zulip organizations.
- Installation documentation, for installing and maintaining a production self-hosted Zulip installation.
- API documentation, for writing integrations or bots using the Zulip API.
- Contributor documentation, for developing the Zulip software, translating, submitting bug reports, or making other contributions to the project.
Zulip has well over 150,000 words of documentation. If you can’t find what you’re looking for, please let us know! Further information on the Zulip project and its features can be found athttps://zulip.com.
This site contains our installation and contributor documentation. If this is your first time here, you may want to start with Production installation or Contributing guide.
Contents:
-
- Zulip overview
* Getting started - Zulip architectural overview
* Key codebases
* Usage assumptions and concepts
* Components
* Glossary - Directory structure
* Core Python files
* HTML templates
* JavaScript, TypeScript, and other frontend assets
* Tests
* Management commands
* Scripts
* API and bots
* Production Puppet configuration
* Additional Django apps
* Jinja2 compatibility files
* Translation files
* Documentation - Release lifecycle
* Server and web app
* Client apps
* API bindings - Version history
* Zulip Server 10.x series (development)
* Zulip Server 9.x series
* Zulip Server 8.x series
* Zulip Server 7.x series
* Zulip Server 6.x series
* Zulip Server 5.x series
* Zulip Server 4.x series
* Zulip Server 3.x series
* Zulip Server 2.1.x series
* Zulip Server 2.0.x series
* Zulip Server 1.9.x series
* Zulip Server 1.8.x series
* Zulip Server 1.7.x series
* Zulip Server 1.6.x and older
* Upgrade notes
- Zulip overview
-
- Requirements and scalability
* Server
* Credentials needed
* Scalability - Install a Zulip server
* Installation process overview
* Step 0: Set up a base server
* Step 1: Download the latest release
* Step 2: Install Zulip
* Step 3: Create a Zulip organization, and log in
* Getting started with Zulip - Troubleshooting and monitoring
* Overview and resources
* Using supervisorctl
* Troubleshooting services
* Monitoring
* Memory leak mitigation
* Troubleshooting the Zulip installer - Management commands
* Running management commands
* manage.py shell
* Other useful manage.py commands
* Custom management commands - Server configuration
* Making changes
* Specific settings
* Zulip announcement list
* Enjoy your Zulip installation! - System configuration
* Truthy values
* [machine]
* [deployment]
* [application_server]
* [postfix]
* [postgresql]
* [memcached]
* [loadbalancer]
* [http_proxy]
* [sentry] - Mobile push notification service
* Signing up
* Plan management
* Why a push notification service is necessary
* Security and privacy
* Rate limits
* Updating your server’s registration
* Deactivating your server’s registration
* Sending push notifications directly from your server - Upgrade Zulip
* Upgrading to a release
* Upgrading from a Git repository
* Updating settings.py inline documentation
* Troubleshooting and rollback
* Deployment hooks
* Preserving local changes to service configuration files
* Upgrading the operating system
* Upgrading PostgreSQL - Modify Zulip
* Making changes
* Applying changes from main
* Contributing patches - Security model
* Secure your Zulip server like your email server
* Encryption and authentication
* Messages and history
* Users and bots
* User-uploaded content and user-generated requests
* Rate limiting
* Final notes and security response - Authentication methods
* Email and password
* Plug-and-play SSO (Google, GitHub, GitLab)
* LDAP (including Active Directory)
* SAML
* Apache-based SSO with REMOTE_USER
* Sign in with Apple
* OpenID Connect
* JWT
* Configuring a custom Python wrapper around the authenticate mechanism
* Adding more authentication backends
* Development only - Backups, export and import
* Backups
* Data export
* Import into a new Zulip server
* Compliance exports
* Database-only backup tools - PostgreSQL database details
* Separate PostgreSQL database
* PostgreSQL warm standby
* PostgreSQL vacuuming alerts - File upload backends
* S3 backend configuration
* S3 local caching
* nginx DNS nameserver configuration
* S3 bucket policy
* Migrating from local uploads to Amazon S3 backend
* S3 data storage class
* Data export bucket - Installing SSL certificates
* Manual install
* Certbot (recommended)
* Self-signed certificate
* Troubleshooting - Outgoing email
* How to configure
* Email services
* Troubleshooting - Deployment options
* Installing Zulip from Git
* Zulip in Docker
* Zulip installer details
* Installing on an existing server
* Deployment hooks
* Running Zulip’s service dependencies on different machines
* Using an alternate port
* Customizing the outgoing HTTP proxy - Reverse proxies
* Installer options
* nginx configuration
* Apache2 configuration
* HAProxy configuration
* Other proxies - Hosting multiple organizations
* Subdomains
* Open realm creation - Incoming email integration
* Local delivery setup
* Polling setup - Video call providers
* Jitsi
* Zoom
* BigBlueButton - GIPHY GIF integration
* Apply for API key - SCIM provisioning
* Server configuration
* Additional options
- Requirements and scalability
-
- Contributing guide
* Zulip development community
* Ways to contribute
* Your first codebase contribution
* What makes a great Zulip contributor?
* User feedback
* Outreach programs
* Stay connected
* Help others find Zulip - Zulip Code of Conduct
* Expected behavior
* Unacceptable behavior
* Reporting and enforcement
* Scope
* License and attribution
* Moderating the Zulip community - How we communicate
* Providing suggestions and feedback
* Handling disagreements
* Expressing your appreciation - Asking great questions
* Where to ask your question
* How to ask a great question
* Follow the community guidelines - Design discussions
* Guidelines for all participants
* Participant roles
* Guidelines for code contributors
* Guidelines for community moderators
* Guidelines for decision makers - Commit discipline
* Each commit must be coherent
* Commits should generally be minimal
* Write a clean commit history
* Commit messages - Code style and conventions
* Be consistent with existing code
* Follow Zulip conventions and practices
* Python-specific conventions and practices
* JavaScript and TypeScript conventions and practices
* HTML and CSS
* Dangerous constructs in Django
* Dangerous constructs in JavaScript and TypeScript - Reviewing Zulip code
* Principles of code review
* How to review code
* Review process and communication
* Additional resources - Submitting a pull request
* Write clear code
* Organize your proposed changes
* Explain your changes
* Review your own work
* Submit your pull request for review
* Draft pull requests
* Demonstrating visual changes - Pull request review process
* Labels for managing the stages of pull request review
* Stages of a pull request review
* How to help move the review process forward - Continuing unfinished work
* Find work to be completed
* Review existing work and feedback
* Decide how to use prior work
* Credit prior work in your commit history
* Present your pull request - Using zulipbot
* Usage - Reporting bugs
* What to include in a bug report
* Filing a GitHub issue
* Starting a conversation about a possible bug
* Managing bug reports - Suggesting features and improvements
* What to include in your proposal
* Starting a conversation about a suggested feature or improvement
* Filing a GitHub issue - Counting contributions
* How the contribution stats are calculated
* Old email addresses
* Relevant source code - Licensing
* Contributing your own work
* Contributing someone else’s work
- Contributing guide
-
- Development environment installation
* Requirements
* Recommended setup
* Vagrant setup
* Advanced setup
* Slow internet connections
* Installing remotely
* Next steps - Recommended setup
* Requirements
* Step 0: Set up Git & GitHub
* Step 1: Install prerequisites
* Step 2: Get Zulip code
* Step 3: Start the development environment
* Step 4: Developing
* Next steps
* Troubleshooting and common errors
* Specifying an Ubuntu mirror
* Specifying a proxy
* Using a different port for Vagrant
* Customizing CPU and RAM allocation - Advanced setup
* Installing directly on Ubuntu, Debian, CentOS, or Fedora
* Installing using Vagrant with VirtualBox on Windows 10
* Using the Vagrant Hyper-V provider on Windows (beta)
* Newer versions of supported platforms - Using the development environment
* Common
* Server
* Web
* Mobile - Developing remotely
* Connecting to the remote environment
* Setting up user accounts
* Setting up the development environment
* Running the development server
* Making changes to code on your remote development server
* Using an nginx reverse proxy - Authentication in the development environment
* Email and password
* Google
* GitHub
* GitLab
* Apple
* SAML
* When SSL is required
* Testing LDAP in development
* Two factor authentication
* Password form implementation - Testing the installer
* Configuring
* Running a test install
- Development environment installation
-
- Writing a new application feature
* General process
* Example feature - Writing views in Zulip
* What this covers
* What is a view?
* Modifying urls.py
* Writing human-readable views
* Writing API REST endpoints
* Legacy endpoints used by the web client
* Incoming webhook integrations - Life of a request
* A request is sent to the server, and handled by nginx
* Static files are served directly by nginx
* nginx routes other requests between Django and Tornado
* Django routes the request to a view in urls.py files
* Views serving HTML are internationalized by server path
* API endpoints use REST
* Django calls rest_dispatch for REST endpoints, and authenticates
* The view will authorize the user, extract request variables, and validate them
* Results are given as JSON - Reading list
* General programming/IT
* Python
* Java/Android
* JavaScript/ECMAScript
* TypeScript
* Git/version control systems (VCS)
* Computer science/algorithms
* Community experience
* Competitions/camps
* Massive open online courses (MOOC) platforms - Screenshot and GIF software
* Screenshot tools by platform
* GIF tools by platform - Shell tips
* The prompt ($)
* Tilde character (~)
* Change directory (cd)
* Running commands as root (sudo)
* Escaping characters
* Sequencing commands
* Splitting commands into multiple lines
* Arguments
* Shebang
* Understanding commands
* Cheatsheet
* Git
- Writing a new application feature
-
- Quick start
- Set up Git
* Install and configure Git, join GitHub
* Get a graphical client - Zulip-specific tools
* Set up Git repo script
* Configure continuous integration for your Zulip fork
* Reset to pull request
* Fetch a pull request and rebase
* Fetch a pull request without rebasing
* Push to a pull request
* Delete unimportant branches
* Merge conflict on pnpm-lock.yaml file - How Git is different
- Important Git terms
* branch
* cache
* checkout
* commit
* fast-forward
* fetch
* hash
* head
* HEAD
* index
* pull
* push
* rebase - Get Zulip code
* Step 1a: Create your fork
* Step 1b: Clone to your machine
* Step 1c: Connect your fork to Zulip upstream
* Step 2: Set up the Zulip development environment
* Step 3: Configure continuous integration for your fork - Working copies
* Workflows
* Relevant Git commands - Using Git as you work
* Know what branch you’re working on
* Keep your fork up to date
* Work on a feature branch
* Run linters and tests locally
* Stage changes
* Commit changes
* Push your commits to GitHub
* Examine and tidy your commit history
* Force-push changes to GitHub after you’ve altered your history - Pull requests
* Draft pull requests
* Create a pull request
* Update a pull request - Collaborate
* Fetch another contributor’s branch
* Check out a pull request locally - Fixing commits
* Fixing the last commit
* Fixing older commits
* Squashing commits
* Reordering commits
* Pushing commits after tidying them - Reviewing changes
* Changes on (local) working tree
* Changes within branches
* Changes between branches - Get and stay out of trouble
* Undo a merge commit
* Restore a lost commit
* Recover from a git rebase failure
* Working from multiple computers - Git cheat sheet
* Common commands
* Detailed cheat sheet
-
- Testing overview
* Running tests
* Major test suites
* Other test suites
* Internet access inside test suites - Linters
* Overview
* Running the linters
* General considerations
* Lint checks
* lint
* Philosophy - Backend Django tests
* Overview
* Running tests
* Writing tests
* Zulip testing philosophy
* Testing considerations - JavaScript/TypeScript unit tests
* How the node tests work
* Handling dependencies in unit tests
* Creating new test modules
* Verifying HTML templates with mock_template
* Coverage reports
* Editor debugger integration
* Webstorm integration setup
* Running tests with the debugger - Web frontend black-box Puppeteer tests
* Running tests
* How Puppeteer tests work
* Debugging Puppeteer tests
* Writing Puppeteer tests - Python static type checker (mypy)
* Installing mypy
* Running mypy on Zulip’s code locally
* Mypy is there to find bugs in Zulip before they impact users
* Mypy stubs for third-party modules
* Working with types from django-stubs
* Using @overload to accurately describe variations
* Best practices
* Troubleshooting advice - TypeScript static types
* Type checking
* Linting and style
* Migration strategy - Continuous integration (CI)
* Goals
* GitHub Actions - Manual testing
* Basic stuff - Testing philosophy
* Effective testing allows us to move quickly
* Test suite performance and reliability are critical
* Integration testing or unit testing?
* Avoid duplicating code with security impact
* Share test setup code
* What isn’t tested probably doesn’t work
- Testing overview
-
- Provisioning and third-party dependencies
* Provisioning
* Philosophy on adding third-party dependencies
* System packages
* Python packages
* JavaScript and other frontend packages
* Node.js and pnpm
* ShellCheck and shfmt
* Puppet packages
* Other third-party and generated files
* Modifying provisioning - Settings system
* Server settings
* Realm settings - HTML and CSS
* Zulip CSS organization
* Editing Zulip CSS
* CSS style guidelines
* Validating CSS
* HTML templates
* Static asset pipeline - Accessibility
* Guidelines
* Tools
* GitHub issues
* Additional resources - Real-time push and events
* Generation system
* Delivery system
* The initial data fetch
* Schema changes - Sending messages
* Message lists
* Compose area
* Backend implementation
* Local echo
* Putting it all together
* Message editing
* Soft deactivation - Notifications in Zulip
* Important corner cases
* The mobile/email notifications flow - Queue processors
* Adding a new queue processor
* Publishing events into a queue
* Clearing a RabbitMQ queue - Unread counts and the pointer
* Pointer logic
* Unread count logic
* Testing and development - Markdown implementation
* Testing
* Changing Zulip’s Markdown processor
* Per-realm features
* Zulip’s Markdown philosophy
* Zulip’s changes to Markdown - Caching in Zulip
* Backend caching with memcached
* In-process caching in Django
* Browser caching of state - Performance and scalability
* Load profiles
* Major Zulip endpoints
* Queue processors and cron jobs
* Service scalability - Realms in Zulip
* Creating realms
* Subdomains - Management commands
* Writing management commands - Schema migrations
* Automated testing for migrations
* Schema and initial data changes - URL hashes and deep linking
* Hashchange
* Server-initiated reloads
* All reloads - Emoji
* Emoji codes
* Tooling
* Picking emoji names - Onboarding Steps
* Configuring a New Onboarding Step - Full-text search
* The default full-text search implementation
* Multi-language full-text search - Email
* Development and testing
* Email templates - Analytics
* Analytics backend overview
* The *Count database tables
* CountStats
* The FillState table
* Performance strategy
* Backend testing
* LoggingCountStats
* Analytics UI development and testing - Clients in Zulip
* Analytics
* Integrations - Logging and error reporting
* Backend error reporting
* Blueslip frontend error reporting
* Frontend performance reporting - Typing indicators
* Privacy settings
* Writing user
* Server
* Receiving user
* Ecosystem
* Roadmap - Upgrading Django
- Zulip server release checklist
* A week before the release
* Final release preparation
* Executing the release
* Post-release - Zulip PyPI packages release checklist
* Other PyPI packages maintained by Zulip - UI: input pills
* Setup
* Basic usage
* Typeahead - Presence
- Unread message synchronization
- Billing (Development)
* Common setup
* Manual testing
* Upgrading Stripe API versions
* Writing tests - Widgets
* What is a widget?
* /me messages
* Polls, todo lists, and games
* zform (trivia quiz bot)
* Data flow - Slash commands
* Data flow
* Typeahead - Thumbnailing
* libvips
* Avatars
* Emoji
* Realm logos
* Realm icons
* File uploads
- Provisioning and third-party dependencies
-
- Documentation systems
* Developer and sysadmin documentation
* Core website documentation
* User-facing documentation
* Automated testing - Writing help center articles
* Guide to writing help center articles
* Writing style
* Markdown features - Documenting an integration
* Markdown macros
* Writing guidelines - Documenting REST API endpoints
* How it works
* Step by step guide
* Why a custom system?
* Debugging schema validation errors - OpenAPI configuration
* Working with the zulip.yaml file
* Zulip Swagger YAML style:
* Tips for working with YAML:
- Documentation systems
-
- Translation guidelines
* Translators’ workflow - Internationalization for developers
* Key details about human language
* Translation process
* Translation resource files
* HTML Templates
* Backend translations
* Frontend translations
* Transifex config
* Transifex CLI setup - Chinese translation style guide(中文翻译指南)
* Note(题记)
* Terms(术语)
* Phrases(习惯用语)
* Others(其它) - Finnish translation style guide
* Guidelines
* Terms
* Other - French translation style guide
* Community
* Rules
* Terms - German translation style guide (Richtlinien für die deutsche Übersetzung)
* Rules
* Terms (Begriffe)
* Phrases (Ausdrücke)
* Other (Verschiedenes) - Hindi translation style guide (हिन्दी अनुवाद शैली मार्गदर्शक)
* Terms (शर्तें)
* Phrases (वाक्यांश)
* Others (अन्य) - Japanese translation style guide
* Rules
* Terms - Polish translation style guide
* Special terms used in Zulip - Russian translation style guide
* Перевод некоторых терминов - Spanish translation style guide
* Términos
* Frases
* Otros - Urdu translation style guide(انداذِ ترجمہ کا رہنما)
* Terms(اصطلاحات)
* Phrases (فِقْرے)
* Others(مختلف دیگر)
- Translation guidelines
-
- Outreach programs overview
* About Zulip
* Outreach program experience - How to apply
* Application criteria
* Getting started
* Putting together your application - How to have an amazing experience
* Your goals
* You and your mentor
* Communication and check-ins
* Peer reviews
* How do I figure out what to work on?
* How else can I contribute?
* Timeline extensions for GSoC - GSoC project ideas
* Project size
* Focus areas
* Project ideas by area - Mentoring
* Who can mentor
* Supporting your mentee
* Managing challenges
- Outreach programs overview