"Basic" How to Setup

Below will be the basics to get PkgBot setup and working. Everything could easily be customized further if desired.

1. Install the prerequisites:

   • Git
   • AutoPkg
   • JSSImporter
   • ngrok
     • Only required if setting up for testing/development work
   • RabbitMQ
     • Using the homebrew instructions or the standalone binary instructions
   • Ngnix
     • Only required if you want run the PkgBot app on a port below 1024 (e.g. port 80/443)
     • Install from source or via homebrew -- numerous guides exist on the interwebs

2. Clone this repo and store it on your AutoPkg Runner.

   • cd /Library/AutoPkg && sudo mkdir PkgBot
   • sudo chgrp -R staff PkgBot && sudo chmod -R g+swx PkgBot
   • git clone [-b <branch>] https://github.com/mlbz521/PkgBot.git PkgBot

3. Install the requirements

   • e.g. /usr/local/autopkg/python -m pip install -r /Library/AutoPkg/PkgBot/requirements.txt
   • Or, if you're simply testing, create a virtual environment and install the requirements

4. Create a Slack Bot/App

   • Note: You can test PkgBot without creating the SlackBot -- obviously expect for the actual Slack notifications part
   • There are numerous tutorials on how to do this and I'm not going to go over the entire process here. I will simply provide the configuration requirements. Official documentation
   • Features/Functionality required
     • Incoming Webhooks
       • Create a webhook to post to the desired channel
     • Interactivity & Shortcuts
       • Set a Request URL under Interactivity that the Bot will send messages too and your server will receive on
         • e.g. https://pkgbot.my.server.org/slackbot/receive
         • or, if using ngrok: https://84c5df439d74.ngrok.io/slackbot/receive (see below)
       • Create a Shortcut; e.g.
         • Where should this shortcut appear? On Messages
         • Name: Promote Pkg
         • Short Description: Promote a pkg to a Policy
         • Callback ID: promote_pkg
       • Set a Options Load URL under Select Menus
         • Use the same URL used in the a Request URL under Interactivity
     • Slash Commands
       • Create a Slash command; e.g.
         • Command: /pkgbot
         • Request URL: https://pkgbot.my.server.org/slackbot/slashcmd
         • Short Description: Ask PkgBot to run AutoPkg
         • Usage Hint: help|<verb> [<args> <options>]
     • Bots
     • OAuth & Permissions
       • Scopes
         • Bot Token Scopes
           • channels:history (upcoming version will need)
           • chat:write
           • commands
           • files:write
           • incoming-webhook
           • reactions:read
           • reactions:write
           • users:read (upcoming version will need)
   • Tokens/Secrets/Keys required:
     • Bot User OAuth Token
     • Signing Secret
     • Bot Name
     • Channel
       • Channel it will be posting into

5. Ensure your PkgBot "server" can communicate with Slack's API

   • For testing, you can utilize ngrok to allow communication from Slack to your dev box.
     • There are numerous tutorials on how to do this and I'm not going to go over the entire process here. I will simply provide the configuration requirements. Official documentation
       • Follow steps two through four above
         • The port used in step four wil need to be defined in your pkgbot_config.yaml
           • e.g. ngrok http 443
     • After starting ngrok, grab the forwarding address from your terminal
       • e.g. Forwarding https://84c5df439d74.ngrok.io -> http://localhost:443
         • the forwarding address is: https://84c5df439d74.ngrok.io
     • The forwarding address will need to be entered into your Slack Bot configuration

6. Optionally, create a private/public certificate for use with Uvicorn (not required when testing with ngrok)

   • Generate a private key and a CSR:
     • openssl req -new -newkey rsa:2048 -nodes -keyout private.key -out pkgbot.csr
   • Obtain a publicly trusted cert using the CSR
   • Update your pkgbot_config.yaml with these values

7. Configure your environments' settings:

   • PkgBot:
     • Starting template can be found in: PkgBot/examples/settings/pkgbot_config.yaml
       • Copy file to: [/path/to/]PkgBot/Settings/pkgbot_config.yaml
     • Some other settings files can be found in: [...]/PkgBot/settings/
   • Celery: [...]/PkgBot/settings/celery.py
   • RabbitMQ: (This is just a minimum example of the possible configurations; the RabbitMQ server must be running to execute these commands)
     • Setup a user for PkgBot services to use
       • Create a user
         • rabbitmqctl add_user "<username>"
       • Set permissions for created user:
         • rabbitmqctl set_permissions "<username>" ".*" ".*" ".*"
       • Delete the default guest user:
         • rabbitmqctl delete_user "guest"
       • Optionally, set the desired level of access for the user:
         • rabbitmqctl set_user_tags <username> <access_level_tag>
   • Ngnix
     • Run the following command to locate the ngnix configuration file path and open it:
       • nginx -t
       • Update the config file with the contents in PkgBot/examples/settings/nginx.conf

8. Start the required services:

   • Change directory: cd /Library/AutoPkg/PkgBot
   • PkgBot: PkgBot.py
   • Celery: /usr/local/autopkg/python -m celery -A PkgBot.celery worker --loglevel=info
   • Celery Beat: /usr/local/autopkg/python -m celery -A PkgBot.celery beat -s Database/schedule_db --loglevel=info
   • RabbitMQ: rabbitmq-server
   • nginx
   • To ensure the required services are always running:
     • Example LaunchDaemon services are provided (in PkgBot/examples/launchdaemons) that can be put in /Library/LaunchDaemons then bootstrapped and enabled:
       • PkgBot: com.github.mlbz521.pkgbot.plist
       • Celery: com.github.mlbz521.pkgbot.celery.plist
     • RabbitMQ: sudo brew services start rabbitmq
       • This will create a service managed by Brew
     • Nginx: sudo brew services start nginx
       • This will create a service managed by Brew