github-mirror/discourse
2
0
Fork 0
mirror of https://github.com/discourse/discourse.git synced 2024-11-22 11:15:05 +08:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Update ADMIN-QUICK-START-GUIDE.md (#22788)

Browse Source 
This is a fairly extensive update to add checklists and to reorganize the presented information so it is more accessible. Some info is relegated to links to docs on meta. For convenience and regular reference, this topic is now linked to from a GETTING STARTED button next to the site title as long as the site is in bootstrap mode.
This commit is contained in:
Tobias Eigen 2023-07-27 08:44:38 -07:00 committed by GitHub
parent db0aef1192
commit 84ffea4916
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 111 additions and 102 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

213
docs/ADMIN-QUICK-START-GUIDE.md
View File

@ -1,42 +1,118 @@
Congratulations, you are now the proud owner of your very own [Civilized Discourse Construction Kit](https://www.discourse.org). :hatching_chick:
### Getting Started
![](https://www.discourse.org/images/welcome/welcome-to-discourse-hosting-690x314.jpg)
If you haven't already, launch the [setup wizard](/wizard) and go through the steps to configure your site. You can run the wizard as many times as you want, it's completely safe!
# 1. Initial setup
Discourse is a powerful, versatile platform with many options. To help you make sure you're covering all the bases as you get started with your new community, we provided some checklists and guidance below. If you haven't already, [complete the Setup Wizard](/wizard) which covers the essentials.
> Note: To make launching your new site easier, all new members will have daily summary emails enabled (instead of the usual weekly) and be given a higher level of trust. See below to learn more about the trust system and bootstrap mode.
You now also need to [test your email](#h-4-maintaining-your-discourse-server-14) to make sure it is configured correctly, otherwise new signups and notifications will not work.
### Admin Dashboard
For more assistance on configuring and running your Discourse forum, see [meta.discourse.org](https://meta.discourse.org/).
### Recommended before inviting most of your members
It is essential that you provide a meaningful name and description for your site, so your members immediately know what your community is about. Also edit the welcome topic. In a few sentences, let everyone know who this community is for, what they can expect to find here, and what you'd like them to do as soon as they arrive.
Exercise your admin superpowers any time via the admin dashboard at
[] Add your site name and description
[] Edit your welcome topic
[**/admin**](/admin)
### Legal
You are responsible for providing your organization's details and legal notices. Discourse will place boilerplate templates in your #staff category when you add your company name in the setup wizard.
You can also access it via the "hamburger" <kbd>☰</kbd> menu in the upper right: Admin functions are generally marked with the wrench :wrench: icon, so look for that.
[] Add your company name and details
[] Edit the boilerplate TOS or provide a link to the TOS on your main site
[] Edit the boilerplate Privacy Notice or provide a link to the Privacy Notice on your main site
### Customization options
Out of the box, Discourse provides a clean, friendly design. Via the setup wizard and admin dashboard, you can make changes easily to make your site look and feel unique. No special skills are required, but advanced options are available if you have access to the tech skills.
[] Upload logo images
[] Change the color scheme
[] Change the font used for text and headers
[] Install a different site theme
[] Choose a different homepage style
[] Customize the default categories and tags shown on the sidebar
[] Add a custom section to the sidebar
[] Add custom user fields to let members provide more info about themselves
[details="Advanced options"]
Discourse is very configurable and there is a great deal programmers and web designers can do to customize it, integrate it into other platforms, or address any use case. Users going down this route are highly encouraged to join meta.discourse.org, our support community, to learn from what others have and to give and get advice.
[] Add one or more social login options: [Google](https://meta.discourse.org/t/configuring-google-oauth2-login-for-discourse/15858), [Twitter](https://meta.discourse.org/t/configuring-twitter-login-for-discourse/13395), [Facebook](https://meta.discourse.org/t/configuring-facebook-login-for-discourse/13394), [GitHub](https://meta.discourse.org/t/configuring-github-login-for-discourse/13745), [Discord](https://meta.discourse.org/t/configure-discord-login-for-discourse/127129?u=tobiaseigen), [Apple](https://www.discourse.org/plugins/apple-login), [Amazon, LinkedIn, and Microsoft](https://www.discourse.org/plugins/amazon-linkedin-microsoft-login)
[] [Embed Discourse in your WordPress website](https://github.com/discourse/wp-discourse), or [on your static HTML site](https://meta.discourse.org/t/embedding-discourse-comments-via-javascript/31963)
[] Set up [single-sign on](https://meta.discourse.org/t/official-single-sign-on-for-discourse/13045) with your main site
[] [Build your own login method](https://meta.discourse.org/t/login-to-discourse-with-custom-oauth2-provider/14717)
[] [Create your own theme](https://meta.discourse.org/docs?topic=93648)
[] [Interact with Discourse from other applications using the API](https://meta.discourse.org/t/create-and-configure-an-api-key/230124?u=tobiaseigen)
[/details]
# 2. Invite your members
Once you've done the initial setup, you're ready to invite your founding members who can help you finish setup and get some conversations started. Go to [your invites page](/my/invited) and look for the <kbd>+ Invite</kbd> button to create invite links you can share or directly email everyone you want to have in your community. **Be sure to follow up to make sure they join and start participating!**
### To complete together with your founding members
[] Founding members sign up and commit to visiting and participating regularly (at least 3 recommended)
[] Members provide their name, bio and picture
[] Create interesting topics (at least 5 topics and 30 replies recommended)
[] Start talking in chat
[] Talk in #feedback about how to use the site and how it is organized
[] Review and edit the provided Community Guidelines (FAQ)
### When you're ready, launch your community!
[] For public sites, link your community everywhere and promote it so people can find it!
[] Send out invitations by email and by sharing invite links in channels used by your community (you can also create [bulk invites](https://meta.discourse.org/t/sending-bulk-user-invites/16468) and [invite users into groups](https://meta.discourse.org/t/invite-individual-users-to-a-group/15544))
[] Keep following up to make sure as many people as possible are joining and communicating with each other on your Discourse site
> **Note:** To make launching your new site easier, all new members will have daily email summary emails enabled (instead of the usual weekly) and be given a higher level of trust. See below to learn more about the trust system and bootstrap mode.
# 3. Managing your forum
### Admin and Moderator tools
Exercise your admin superpowers anytime via the [admin dashboard](/admin). You can access it via the :wrench: admin link on the menu. Admin and moderator functions are generally marked with the wrench :wrench: icon, so look for that.
### Staff
Staff members are official representatives of this community. There are two kinds of Staff:
Staff members are official representatives of this community. There are two kinds of Staff in Discourse:
1. **Admins**, who can do anything and configure anything on this site.
2. **Moderators**, who can edit all posts and users, but cannot add categories or change any site settings.
2. **Moderators**, who can edit all posts and users but cannot add categories or change any site settings.
To add additional staff members:
Promoting members of your community is easy:
- have them sign up on the site (or [send out an invitation to join via your user page](/my/invited))
- click the admin button :wrench: on their user page
- select :wrench: admin wrench on their user page
- look for the <kbd>Grant Admin</kbd> and <kbd>Grant Moderator</kbd> buttons there
### Social Logins
### Categories
You have three default categories:
Users can log in with traditional local username and password accounts. You may want to add:
1. [General](/category/general) – create topics here that don't fit into any other existing category.
2. [Site Feedback](/category/site-feedback) – Discussion about this site, its organization, how it works, and how you and your community can improve it. [It's important!](https://meta.discourse.org/t/5249)
3. [Staff](/category/staff) – Visible only to staff (admins and moderators)
**Only create a few initial categories**, as you can overwhelm your community. You can always add more categories later and easily bulk recategorize topics. You and your members will have a better experience if you figure out the organization as you go rather than assuming you'll get it all right from the beginning.
- [Google logins](https://meta.discourse.org/t/configuring-google-oauth2-login-for-discourse/15858)
- [Twitter logins](https://meta.discourse.org/t/configuring-twitter-login-for-discourse/13395)
- [Facebook logins](https://meta.discourse.org/t/configuring-facebook-login-for-discourse/13394)
- [GitHub logins](https://meta.discourse.org/t/configuring-github-login-for-discourse/13745)
Select the :wrench: admin wrench on the [categories page](https://dev.discourse.org/categories) to add a category. You can set security per-category so only certain groups of users can see topics in that category.
You can also [set up single-sign on](https://meta.discourse.org/t/official-single-sign-on-for-discourse/13045), or even [build your own login method](https://meta.discourse.org/t/login-to-discourse-with-custom-oauth2-provider/14717).
Every category has an initial "About this category" topic which you will want to edit to suit your needs. This topic will be pinned to the top of the category, and the description you enter in the first paragraph will appear throughout. Be sure to give your new category a good, clear description, so people understand what belongs there!
In addition to categories, Discourse allows you to organize topics with tags. Tags offer a flexible alternative to categories. Create tags when editing topics.
### Pinned topics and banners
Note how pinning topics works in Discourse:
- Once someone reads to the bottom of a pinned topic, it is automatically unpinned for them specifically. They can change this via the personal pin controls at the bottom of the topic.
- When staff pins a topic, they can pin it globally to all topic lists, or just within its category.
If a pin isn't visible enough, you can also turn one single topic into a **banner**. The banner topic floats on top of all topics and all primary pages. Users can permanently dismiss this floating banner by clicking the × in the upper right corner.
To make (or remove) a pin or banner, use the topic :wrench: admin wrench.
### Forum moderation and community building
Discourse has a trust level system where users earn trust over time and gain abilities to assist in governing their community. The trust level system is designed to offer safe defaults, even for public communities with no active moderation. You should not have to change them. For more details, see [Understanding Trust Levels](https://blog.discourse.org/2018/06/understanding-discourse-trust-levels/).
> **0 (new) → 1 (basic) → 2 (member) → 3 (regular) → 4 (leader)**
To make launching your new site easier, all new users will have daily email summary emails enabled (instead of the usual weekly) and be given a higher level of trust that allows them to bypass new user restrictions. Once you've reached a certain number of users (adjustable via the [Bootstrap mode admin setting](/admin/site_settings/category/all_results?filter=bootstrap)) new users will have to spend 15 minutes reading to remove new user restrictions, or be invited by another trusted user.
# 4. Maintaining your Discourse server
### Test Your Email
@ -48,73 +124,6 @@ Email is required for new account signups and notifications. **Test your email t
If you'd like to enable *replying* to topics via email, [see this howto](https://meta.discourse.org/t/set-up-reply-via-email-support/14003).
### Categories
You have three default categories:
1. [Site Feedback](/category/site-feedback) – general discussion about the site itself. [It's important!](https://meta.discourse.org/t/5249)
2. [Lounge](/category/lounge) – a perk for users at trust level 3 and higher
3. [Staff](/category/staff) – visible only to staff (admins and moderators)
**Don't create too many initial categories**, as you can overwhelm your audience. You can always add more categories, and easily bulk recategorize topics later. It's better to figure out the organization as you go rather than assuming you'll get it all right from the beginning (hint: you won't).
To add a category, visit the [categories page](/categories), then click Create Category at the upper right. You can set security per-category so only certain groups of users can see topics in that category.
Every category has an initial "About this category" topic. This topic will be pinned to the top of the category, and the description you enter will be used in a bunch of places. Be sure to give your new category a good, clear description, so people understand what belongs there!
### Pinned Topics and Banners
Note that pinning topics does work a little differently in Discourse:
- Once someone reads to the bottom of a pinned topic, it is automatically unpinned for them specifically. They can change this via the personal pin controls at the bottom of the topic.
- When staff pins a topic, they can pin it globally to all topic lists, or just within its category.
If a pin isn't visible enough, you can also turn one single topic into a **banner**. The banner topic floats on top of all topics and all primary pages. Users can permanently dismiss this floating banner by clicking the &times; in the upper right corner.
To make (or remove) a pin or a banner, use the admin wrench at the top right or bottom of the topic.
### New User Sandbox and the Trust System
If your discussion area is open to the public, new visitors will arrive that are initially strangers to the community. Discourse has a [trust system](https://blog.discourse.org/2018/06/understanding-discourse-trust-levels/) where users can, over time, earn the trust of the community and gain abilities to assist in governing their community.
Discourse is designed to offer safe defaults for public communities, even with no active moderation.
> **0 (new) &rarr; 1 (basic) &rarr; 2 (member) &rarr; 3 (regular) &rarr; 4 (leader)**
All new users start out in a sandbox with restrictions for everyone's safety. **Trust level 0 (new) users _cannot_** &hellip;
- post more than 2 hyperlinks
- post more than 1 image
- post file attachments
- send personal messages
- flag posts or topics
- have actual links in the "about me" field of their profile
- @name mention more than 2 users in a post
Every action a user can take is rate limited for safety, and especially so for new users. But don't worry, new users can [transition to trust level 1](https://blog.discourse.org/2018/06/understanding-discourse-trust-levels/) in about 10 minutes of reading.
To make launching your new site easier, all new users will have daily email summary emails enabled (instead of the usual weekly) and be given a higher level of trust that allows them to bypass new user restrictions. Once you've reached a certain number of users (adjustable via the [Bootstrap mode admin setting](/admin/site_settings/category/all_results?filter=bootstrap)) new users will have to spend 15 minutes reading to remove new user restrictions, or be invited by another trusted user.
### Building Your Community
Be patient; building communities is hard. Before launching, be sure to:
1. Clearly define your community's purpose in a pinned or banner topic.
2. Seed the discussion with interesting topics.
3. Commit to visiting and participating regularly.
4. Link your community everywhere and promote it so people can find it.
There's more advice at [Building a Discourse Community](https://blog.discourse.org/2014/08/building-a-discourse-community/).
### Sending Invitations
One way to get people to visit your site is to invite them via email. You can do this via:
- The Invite button at the bottom of the topic.
- The Invite area on your profile page.
The invite area on your profile page also includes advanced Staff methods of [sending bulk invites](https://meta.discourse.org/t/sending-bulk-user-invites/16468), and [inviting users into groups](https://meta.discourse.org/t/invite-individual-users-to-a-group/15544).
### Maintenance
- One CPU and 1GB of memory, with swap, is the minimum for a basic Discourse community. As your community grows you may need more memory or CPU resources.
@ -123,22 +132,22 @@ The invite area on your profile page also includes advanced Staff methods of [se
- You should get an email notification when new versions of Discourse are released. To update your instance via our easy one click upgrade process, visit [/admin/upgrade](/admin/upgrade).
- Some other things you might eventually want to set up:
- [Automatic daily backups](https://meta.discourse.org/t/configure-automatic-backups-for-discourse/14855)
- [HTTPS support](https://meta.discourse.org/t/allowing-ssl-for-your-discourse-docker-setup/13847)
- [Content Delivery Network support](https://meta.discourse.org/t/enable-a-cdn-for-your-discourse/14857)
- [Reply via Email](https://meta.discourse.org/t/set-up-reply-via-email-support/14003)
- [Import and Export your data](https://meta.discourse.org/t/move-your-discourse-instance-to-a-different-server/15721)
- [Change the domain name](https://meta.discourse.org/t/how-do-i-change-the-domain-name/16098)
- [Multiple Discourse instances on the same server](https://meta.discourse.org/t/multisite-configuration-with-docker/14084)
- [Import old content from vBulletin, PHPbb, Vanilla, Drupal, BBPress, etc](https://github.com/discourse/discourse/tree/main/script/import_scripts)
- A firewall on your server? [Configure firewall](https://meta.discourse.org/t/configure-a-firewall-for-discourse/20584).
- A user friendly [offline page when rebuilding or upgrading?](https://meta.discourse.org/t/adding-an-offline-page-when-rebuilding/45238)
- Embed Discourse [in your WordPress install](https://github.com/discourse/wp-discourse), or [on your static HTML site](https://meta.discourse.org/t/embedding-discourse-comments-via-javascript/31963)
### Optional things you might eventually want to set up
[] [Automatic daily backups](https://meta.discourse.org/t/configure-automatic-backups-for-discourse/14855)
[] [HTTPS support](https://meta.discourse.org/t/allowing-ssl-for-your-discourse-docker-setup/13847)
[] [Content Delivery Network support](https://meta.discourse.org/t/enable-a-cdn-for-your-discourse/14857)
[] [Reply via Email](https://meta.discourse.org/t/set-up-reply-via-email-support/14003)
[] [Import and Export your data](https://meta.discourse.org/t/move-your-discourse-instance-to-a-different-server/15721)
[] [Change the domain name](https://meta.discourse.org/t/how-do-i-change-the-domain-name/16098)
[] [Multiple Discourse instances on the same server](https://meta.discourse.org/t/multisite-configuration-with-docker/14084)
[] [Import old content from vBulletin, PHPbb, Vanilla, Drupal, BBPress, etc](https://github.com/discourse/discourse/tree/main/script/import_scripts)
[] [Configure a firewall on your server](https://meta.discourse.org/t/configure-a-firewall-for-discourse/20584).
[] [A user friendly offline page when rebuilding or upgrading](https://meta.discourse.org/t/adding-an-offline-page-when-rebuilding/45238)
### Need more Help?
For more assistance on configuring and running your Discourse forum, see [meta.discourse.org](https://meta.discourse.org).
# Resources and help are a click away
* Read our blog post [Building a Discourse Community](http://blog.discourse.org/2014/08/building-a-discourse-community/)
* Join meta.discourse.org, our official community, to discuss features, bugs, hosting, development and general support with other Discourse users
* Search <https://meta.discourse.org/docs> for detailed documentation about using discourse, moderation, the admin dashboard, theming and customization, and much much more.
----