Install plugins on a self-hosted site

Discourse · August 22, 2014, 2:59am

This guide assumes that you have a self-hosted standard installation. We only support the standard method of install here, so these instructions assume you have a standard install.

This guide only applies to self-hosted Discourse instances. If you are using a managed hosting service, the available plugins are controlled by your hosting provider. For example, on our hosting these specific plugins are available by hosting tier.

In this tutorial, we’ll install the Discourse Solved plugin.

This tutorial requires an understanding of how to use GitHub repos, specifically, how to get or copy the git clone URL and how to edit YAML (*.yml) files via the terminal using nano, specifically how to save and exit on nano. YAML files strongly follow indentations, so be sure to respect these as you copy and paste and edit the necessary *.yml for your Discourse instance.

Copy the plugin’s GitHub git clone url.
Access your container’s app.yml file (present in /var/discourse/containers/)
```
cd /var/discourse
nano containers/app.yml
```
Add the plugin’s repository URL to your container’s app.yml file:
```
hooks:
  after_code:
    - exec:
        cd: $home/plugins
        cmd:
          - sudo -E -u discourse git clone https://github.com/discourse/docker_manager.git
          - sudo -E -u discourse git clone https://github.com/discourse/discourse-solved.git
```
Add the plugin’s git clone url just below the line containing git clone https://github.com/discourse/docker_manager.git)

Follow the existing format of the docker_manager.git line; if it does not contain sudo -E -u discourse then insert - git clone https://github.com/discourse/discourse-solved.git.
Rebuild the container:
```
cd /var/discourse
./launcher rebuild app
```
That’s it, you’ve successfully installed the Discourse Solved plugin on your Discourse instance!

If your plugin is hosted in a private repository

You must use an OAuth token:

With the OAuth token, you can install your plugin in the same way as a public repo, and you don’t need to create a SSH key.

hooks:
  after_code:
    - exec:
        cd: $home/plugins
        cmd:
              - sudo -E -u discourse git clone https://<token>@github.com/owner/repo.git

We strongly advise you to use OAuth tokens for plugins in private repositories. However, if you cannot, see below.

SSH Key Private Install Steps

Assuming that your private git repo is hosted on GitHub, you need to add your server’s user public SSH key to GitHub repo Deploy keys (https://github.com/SecretOrg/secret-plugin/settings/keys).
Modify app.yml file as shown in below example:

run:
  - exec: echo "Beginning of custom commands"
  
  - exec: cd /var/www/discourse && sudo -u discourse bundle install --deployment --without test --without development
  - exec: echo "Host github.com\n\tStrictHostKeyChecking no\n" >> /user/.ssh/config
  - file:
      path: /user/.ssh/id_rsa
      chmod: 600
      contents: |
        -----BEGIN RSA PRIVATE KEY-----
        MIIEogIBAAKCAQEArCQG213utzqE5YVjTVF5exGRCkE9OuM7LCp/FOuPdoHrFUXk
           .... etc ....
        -----END RSA PRIVATE KEY-----
  - file:
      path: /user/.ssh/id_rsa.pub
      chmod: 600
      contents: ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAklOUpkDHrfHY17SbrmTIpNLTGK9Tj .... etc .... user@discourse
  - exec: cd $home/plugins && git clone git@github.com:SecretOrg/secret-plugin.git
  - exec: cd $home && sudo -E -u discourse bundle exec rake db:migrate
  - exec: cd $home && rm -fr tmp/cache
  - exec: cd $home &&  sudo -E -u discourse bundle exec rake assets:precompile
  - exec: rm /user/.ssh/id_rsa
  - exec: rm /user/.ssh/id_rsa.pub

  - exec: echo "End of custom commands"

Rebuild the container:

cd /var/discourse
./launcher rebuild app

Your private plugin should be installed on your Discourse instance.

How to uninstall a plugin

To remove a plugin, simply remove the - git clone https://github.com/... line from your app.yml file and rebuild your site via

cd /var/discourse
./launcher rebuild app

bloomexperiment · February 5, 2024, 7:32am

I updated the guide to use another example plugin instead of Discourse Spoiler Alert, which has been bundled into core.

I used Discourse Solved, but let me know if a different one would be better.

SohaibKhaliq · April 2, 2024, 4:09am

I hosted discourse on Digital Ocean and when i used that format it showed me this error.

FAILED
--------------------
Pups::ExecError: cd /var/www/discourse/plugins && sudo -E -u discourse git clone https://github.com/discourse/docker_manager.git  - sudo -E -u discourse git clone https://github.com/discourse/discourse-solved.git failed with return #<Process::Status: pid 252 exit 129>
Location of failure: /usr/local/lib/ruby/gems/3.2.0/gems/pups-1.2.1/lib/pups/exec_command.rb:132:in `spawn'
exec failed with the params {"cd"=>"$home/plugins", "cmd"=>["sudo -E -u discourse git clone https://github.com/discourse/docker_manager.git  - sudo -E -u discourse git clone https://github.com/discourse/discourse-solved.git"]}
bootstrap failed with exit code 129
** FAILED TO BOOTSTRAP ** please scroll up and look for earlier error messages, there may be more than one.
./discourse-doctor may help diagnose the problem.
2a49220a4ff35feac3c1a9a4a9c1cad1094bde4c9ba321975ebc9ae7ead2bbee

Then i used this format

hooks:
  after_code:
    - exec:
        cd: $home/plugins
        cmd:
          - sudo -E -u discourse git clone https://github.com/discourse/docker_manager.git && sudo -E -u discourse git clone https://github.com/discourse/discourse-solved.git

instead of

hooks:
  after_code:
    - exec:
        cd: $home/plugins
        cmd:
          - sudo -E -u discourse git clone https://github.com/discourse/docker_manager.git
          - sudo -E -u discourse git clone https://github.com/discourse/discourse-solved.git

JammyDodger · May 9, 2024, 10:32am

8 posts were split to a new topic: Formatting issues adding plugins to app.yml

wal · August 13, 2024, 4:21am

sorry for the dumb question but, how should I know if its required to include sudo -E -u discourse or not for the git clone statement?

Moin · August 18, 2024, 5:59am

How does your docker_manager line look like?

wal · August 19, 2024, 12:40pm

none of the other entries in my app.yml had the sudo part so I omitted that and its just worked so far

Overgrow · August 27, 2024, 9:25pm

- exec: echo "Host github.com\n\tStrictHostKeyChecking no\n" >> /user/.ssh/config

Seems like this method is not working anymore.

sh: 1: cannot create /user/.ssh/config: Directory nonexistent

With my self-hosted GIT repository, I’d really like to use SSH keys.

pfaffman · August 27, 2024, 10:20pm

You shouldn’t need an ssh key in the container, just delete this:

Overgrow · August 27, 2024, 10:22pm

Sorry, I don’t think I follow…

My repo is accessible via ssh. How can I get a plugin cloned without SSH key?

pfaffman · August 27, 2024, 10:35pm

Oh. Maybe I’m wrong. Then maybe you need to create that directory with the right permissions m

Overgrow · August 29, 2024, 9:22am

What is confusing is that part of the commands in examples are to be run as root and part as user discourse. It doesn’t seem to be very consisent.

  - exec: cd $home/plugins && git clone git@github.com:SecretOrg/secret-plugin.git

As opposed to

  - exec: cd $home && sudo -E -u discourse bundle exec rake db:migrate

I will do some digging in the running container’s shell.

nwnuyhs · September 2, 2024, 7:40am

This plugin installation is a bit complicated. It would be great if it could be made the same as installing theme.

pfaffman · September 2, 2024, 10:34am

Dashboard.literatecomputing.com will install plugins with a few clicks. You can use it for free by joining the free trial group.

Overgrow · September 2, 2024, 4:38pm

@Discourse, If you want to update the guide, here is the working code:

To use your own SSH keys for accessing a private repository, follow these steps:

Place the private SSH key in /var/discourse/shared/standalone/identity/id_rsa (or another location accessible by the container; if you choose a different location, remember to update the path in the template below accordingly).
Use the following template to add your plugins:

hooks:
  after_code:
    - exec:
        cd: $home/plugins
        cmd:
          # Set private repo access
          - chown $(whoami) /shared/identity/id_rsa && chmod 600 /shared/identity/id_rsa
          - git config --global core.sshCommand "ssh -o StrictHostKeyChecking=no -o IdentitiesOnly=yes -i /shared/identity/id_rsa"

          # My private plugins
          - git clone git@example.com:repo/private-discourse-plugin.git

          # Unset access
          - git config --global --unset core.sshCommand

Jagster · September 2, 2024, 5:36pm

Thanks for something I don’t need that one but I live with simple original.

Do you want to explain why we should use your example? Is it because of this:

use your own SSH keys for accessing a private repository

merefield · September 2, 2024, 5:45pm

Why not just use a token in the URL?

Jagster · September 2, 2024, 6:46pm

Well, we have tools to solve out this riddle

Understanding the Usefulness of Container Configuration Snippets AI

Jagster:

Why someone would like to use that snippet in container/app.ym

gpt-4o:

To effectively answer your question, I need to understand the context around the specific snippet in container/app.yml. Could you please provide more details or the actual snippet you’re referring to? This way, I can give you a precise and helpful explanation.

Jagster:

Sorry, but I needed this composer.

This is the snippet:

”””

hooks:
  after_code:
    - exec:
        cd: $home/plugins
        cmd:
          # Set private repo access
          - chown $(whoami) /shared/identity/id_rsa && chmod 600 /shared/identity/id_rsa
          - git config --global core.sshCommand "ssh -o StrictHostKeyChecking=no -o IdentitiesOnly=yes -i /shared/identity/id_rsa"

          # My private plugins
          - git clone git@example.com:repo/private-discourse-plugin.git

          # Unset access
          - git config --global --unset core.sshCommand

”””

gpt-4o:

Thank you for providing the snippet. This YAML snippet is intended to be included in the container/app.yml configuration file for a Discourse instance. Let’s break down what it does:

hooks:
  after_code:
    - exec:
        cd: $home/plugins
        cmd:
          # Set private repo access
          - chown $(whoami) /shared/identity/id_rsa && chmod 600 /shared/identity/id_rsa
          - git config --global core.sshCommand "ssh -o StrictHostKeyChecking=no -o IdentitiesOnly=yes -i /shared/identity/id_rsa"

          # My private plugins
          - git clone git@example.com:repo/private-discourse-plugin.git

          # Unset access
          - git config --global --unset core.sshCommand

Explanation

Setting Directory:
```
cd: $home/plugins
```
This changes the working directory to where plugins are located ($home/plugins).
Setting Private Repository Access:
```
- chown $(whoami) /shared/identity/id_rsa && chmod 600 /shared/identity/id_rsa
- git config --global core.sshCommand "ssh -o StrictHostKeyChecking=no -o IdentitiesOnly=yes -i /shared/identity/id_rsa"
```
- Changes the ownership of the SSH private key (id_rsa) to the current user and sets its permissions to 600.
- Configures Git to use a custom SSH command which uses the specified private key and disables strict host key checking.
Cloning Private Repository:
```
- git clone git@example.com:repo/private-discourse-plugin.git
```
Clone a private Git repository containing a Discourse plugin.
Unsetting SSH Command:
```
- git config --global --unset core.sshCommand
```
Resets the Git SSH command configuration to its default state.

When and Why to Use This Snippet

Private Repositories: If you have a private Discourse plugin repository that is not publicly accessible and requires SSH key-based authentication.
Automation: This script helps automate the process of setting up access to the private repository, cloning it, and ensuring the environment is reset afterwards. This is useful for continuous deployment setups or automated server provisioning.
Security Management: It handles the SSH keys securely (setting file permissions and then unsetting the custom SSH command), critical for maintaining security posture during automated deployments.

Important Considerations

Ensure your private SSH key (id_rsa) is securely managed and not exposed.
Verify the ownership and permissions are correctly set for your security policies.

For more detailed information and contexts about app.yml and hooks in Discourse, you can check relevant Discourse documentation.

If you have any further questions or need additional details on the configuration, feel free to ask!

rrodrigueznt · October 15, 2024, 6:28pm

Hi! It sounds great! But I don’t know how I must proceed after joining the free trial group! Please, @pfaffman, could you help me? I’m looking to install SAML plugin. It would be great to test Literate Computing to get it installed and running!

Thanks!

Overgrow · October 15, 2024, 9:43pm

My template snippet is for when you don’t have any other means of accessing the Git repo besides an SSH key (for example, with a self-hosted Git repository behind SSH).

Topic		Replies	Views
Is it possible to use a local plugin directory with a docker install? Dev	39	2779	June 16, 2022
What happens next? Installation	10	93	August 15, 2025
Install plugins without direct access to github Support unsupported-install	13	1255	April 17, 2019
I want to install a plugin for development, what should I do? Dev	17	2829	July 24, 2019
Developing Discourse Plugins - Part 1 - Create a basic plugin Developer Guides plugin-guides , tutorial	32	81046	July 8, 2025