Get Started

Easy Ways to Get Started with Cakcuk

You can start using Cakcuk by adding Cakcuk to your workspace directly.

Provision your own Cakcuk

To get started deploying Cakcuk by yourself, make sure you have created the slack app first to get the Slack app token. You can go to Slack Apps and create one if you haven't created your slack app. You also need to keep the verification token as well. It works for validation of each request from Slack. Put those both tokens on your Cakcuk env just like in this section.

When you use Slack Event API, you also need to set events for those you subscribe to. There are three events that you need to submit.

Needed Slack scopes for your Cakcuk

  • app_mentions:read
  • chat:write
  • files:write
  • im:history
  • team:read
  • users:read

More explanations about Slack Scopes you can check here https://api.slack.com/scopes.

Some ways to run Cakcuk by yourself

  • Cakcuk with Slack Event API TLS disabled

    docker run -p 80:80 \ -e MYSQL_HOST="your-mysql-host" \ -e MYSQL_USERNAME="your-mysql-username" \ -e MYSQL_PASSWORD="your-mysql-password" \ -e MYSQL_DATABASE="your-mysql-db-name" \ -e SLACK_TOKEN="your-slack-app-token" \ -e SLACK_VERIFICATION_TOKEN="your-slack-verification-token" \ -e SLACK_EVENT_ENABLED="true" \ isdzulqor/cakcuk:latest
  • TLS disabled doesn't mean you cannot use HTTPS for your Cakcuk. It gives you an option if you want to deploy it with TLS handled by load balancer or the others, for example, Nginx. So it doesn't need to be handled on the application level.

  • Cakcuk with Slack Event API TLS Enabled

    docker run -p 80:80 -p 443:443 \ -e MYSQL_HOST="your-mysql-host" \ -e MYSQL_USERNAME="your-mysql-username" \ -e MYSQL_PASSWORD="your-mysql-password" \ -e MYSQL_DATABASE="your-mysql-db-name" \ -e SLACK_TOKEN="your-slack-app-token" \ -e SLACK_VERIFICATION_TOKEN="your-slack-verification-token" \ -e SLACK_EVENT_ENABLED="true" \ -e TLS_ENABLED="true" \ -e PUBLIC_DOMAINS="your-domain-1,www-your-domain-1" \ isdzulqor/cakcuk:latest
  • If you use TLS enabled. You need to provide public domains that you need to set for PUBLIC_DOMAINS env. It accepts multiple domains separated by comma. Cakcuk uses Let's Encrypt to handle TLS.

  • Cakcuk with Slack RTM API TLS disabled

    docker run -p 80:80 \ -e MYSQL_HOST="your-mysql-host" \ -e MYSQL_USERNAME="your-mysql-username" \ -e MYSQL_PASSWORD="your-mysql-password" \ -e MYSQL_DATABASE="your-mysql-db-name" \ -e SLACK_TOKEN="your-slack-app-token" \ -e SLACK_VERIFICATION_TOKEN="your-slack-verification-token" \ -e SLACK_RTM_ENABLED="true" \ isdzulqor/cakcuk:latest
  • Cakcuk with Slack RTM API TLS Enabled

    docker run -p 80:80 -p 443:443 \ -e MYSQL_HOST="your-mysql-host" \ -e MYSQL_USERNAME="your-mysql-username" \ -e MYSQL_PASSWORD="your-mysql-password" \ -e MYSQL_DATABASE="your-mysql-db-name" \ -e SLACK_TOKEN="your-slack-app-token" \ -e SLACK_VERIFICATION_TOKEN="your-slack-verification-token" \ -e SLACK_RTM_ENABLED="true" \ -e TLS_ENABLED="true" \ -e PUBLIC_DOMAINS="your-domain-1,www-your-domain-1" \ isdzulqor/cakcuk:latest
  • A Bit Differences between Slack Event API & Slack RTM API

    • Slack RTM API doesn't need to expose a public endpoint. Thus it's easier to integrate with your private cluster if you have.
    • Slack Event API needs to has a public endpoint and register it to Slack to be challenged.

    • Slack RTM API uses WebSocket, so it's realtime and lower latency.
    • Slack Event API uses HTTPS webhook, it must have higher latency mostly.

    • Slack RTM API uses higher resource, CPU, memory & bandwidth. WebSocket costs this.
    • Slack Event API uses HTTPS webhook, it eats lower resources.

    • Slack RTM API needs to expose many scopes/permissions, bot Slack scope. It has multiple scopes/permissions aggregated in bot Slack scope. That's why RTM API will consume events that you don't need them as well.
    • Slack Event API can just use Slack scopes/permission as needed.

    More about it https://api.slack.com/events-api and https://api.slack.com/rtm

  • Simply use docker-compose.yaml

    docker-compose -f docker-compose.yaml up -d
  • Make sure you overwrite the environment variables values as you need. Please see the configurations explanations above, either you use Event API or RTM API, with TLS disabled or enabled.

  • Clone the Source on Github


Some Environment Variables Explanation

  • PORT
  • By default, Cakcuk with TLS disabled is using port 80. You can change it as you want by overwriting the PORT env. Keep in mind, it's only for TLS disabled. If you provision your Cakcuk with TLS enabled. It will use port 80 and 443 for sure.

  • LOG_LEVEL
  • By default LOG_LEVEL value is info. It means that logs only print Info, Warn, Error, Fatal, and Panic those are printed on logs. There are 5 types of LOG_LEVEL debug, info, warn, error, fatal, and panic. If you want to print all the logs although is for debugging only. You can overwrite LOG_LEVEL env with debug value.

  • ENCRYPTION_PASSWORD
  • If you have checked special prefix functionality for encrypt= and encrypted option in your Custom Commands. This ENCRYPTION_PASSWORD value is the encryption key for the encryption value. For authentication feature, it also uses this encryption key. Just make sure you customize this ENCRYPTION_PASSWORD env value to keep your sensitive value secured.

  • SUPER_USER_MODE_ENABLED
  • SUPER_USER_MODE_ENABLED is true, means enabled by default. It can be disabled by setting the value to be false. If you play the commands on the Playground. You will automatically have access to Superuser. Just play with SU command, examples are provided with an explanation on the info section.


Default Commands

Cakcuk's Base Commands

Help

Like most Help functions in other CLIs. Help works to display command lists or specific commands for their details, such as for example usage, description, options, etc.

It's pretty straightforward to work with Help. It also works with your Custom Commands. Just try the examples below!

Result
Response
Command Result
Run

- Snippet Examples -


Help only
Oneline help
Command Detail
Online Command Detail
--help on Command


Cuk

Cuk is a command for hitting HTTP/S endpoints. It covers endpoint properties like URL, Query Parameters, Headers, etc. It works pretty simply to support common endpoint usage.

One of the special options that you can explore is --parseResponse, -pr. --parseResponse, -pr is supporting Cak command and your Custom Commands as well.

Result
Response
Command Result
Run

- Snippet Examples -


Header
Query Param on URL
Query Param
URL Param
Plain Text Body Param
Json as Body Param
URL Encoded Param
Multipart - Upload File
Parse Response
Basic Auth


Cak

Cak is a special command to create your Custom Commands. Your commands creation on Playground only hold for 5 minutes. They will be deleted after that.

Just explore Cak command using provided examples. They quite represent Cak functionalities.

Result
Response
Command Result
Run

- Snippet Examples -


Query Param Dynamic
URL Param Dynamic
URL Encoded Dynamic
Multipart Dynamic
Special Prefix
Encrypted Value
Basic Auth
Multi Value & Dynamic
With Scope


Del

Del is a simple command to delete your custom commands. You're not allowed to delete Default Commands. Del supports multiple commands deletion separated by double-and && like the examples below.

Please keep in mind, multiple option values always separated by double-and &&. You're only able to delete commands in your Scopes, except you have Superuser access.

Result
Response
Command Result
Run

- Snippet Examples -


Del Single Command
Del Multiple Commands


Scope

Create, edit, and delete Scopes aka access control list (ACL) for users and commands. It's useful for managing certain custom commands that belong to certain groups. For example, you create two Scopes for developer and infra. You want to make the users and commands that belong to the developer can't be accessed by infra users, and vice versa.

The default scope for the command is public. Commands in public scope can be accessed by anyone in your workspace. Please keep in mind, that Scope creation on Playground also has 5 minutes expiration time.

Result
Response
Command Result
Run

- Snippet Examples -


Show All Scopes
Simple Create Scope
Update or Enlarge scope
Delete Scope
Reduce Scope


SU - Superuser

Access and control to manage Superuser. Superuser is enabled by default. But, it's configurable via environment variable of SUPER_USER_MODE_ENABLED.

Superuser that you set on the Playground has an expiration time. It will hold for 5 minutes like Cak commands & Scopes creation. The only user that's in the Superuser list that's able to set and delete the other users to be Superuser. But for the first-time installation, Superuser can be set by anyone.

The differences between Superuser and Common User

  • Superuser can Read, Create, Update, and Delete all Scopes.
  • Common User is only able to Read, Create, Update, and Delete his Scopes.

  • Superuser can Read, Create, Update, Delete, and Execute all commands.
  • Common User is only able to Read, Create, Update, Delete, and Execute his commands in his scopes.

  • Superuser can Read of all the user's access, the scopes and the commands included.
  • Common User is not allowed.

  • Superuser can Show, Set, and Delete Superuser list group.
  • Common User is only able to Show Superuser list.
Result
Response
Command Result
Run

- Snippet Examples -


Show Superuser List
Set Superuser
Del Superuser


Custom Command

Create your own custom command based on your needs

Create your own custom command with Cak command then execute it. Please keep in mind, the commands you create on the Playground have the expiration time. It takes 5 minutes to be deleted after the creation time.

Your created Custom Commands also have the implicit options that Cuk command has. Like Query parameters, Headers, etc. You can overwrite or add params as you need. Just try the examples below! You need to try it in sequence for each example within the section.

Don't forget to explore Cak command as well for more functionalities as you need.

Result
Response
Command Result
Run

- Snippet Examples -


Create Command
Force Update
Execute Command
No Parse
Create Command
Add Param Value
Execute with Scope


Default Options

General options that you can use it in almost all of Cakcuk commands

--outputFile, -of

Printing result to be file output. It's a single option. Just add --outputFile, -of in your command. Please note it's only working in your workspace.

--filter, -f

Filtering result that's containing some keyword. Works like grep command in terminal. --filter, -f is case insensitive. Example usage: --filter=this is keywords. Just play the playground to see the result!

--printOptions, -po

It will print options when you execute the command in your workspace. Just like the Preview tab in the command section of the play editor. It's useful for you to ensure you input the correct value for each option as you want. Something like avoiding typo.

--noResponse, -nr

It will print no response from your executed command in your workspace. Just add --noResponse, -nr in your command. It's fit for your use-case which is for post/put something, like triggering CI or something like that you don't need the response.

--noParse, -np

It will ignore --parseResponse, -pr value. It's useful for debugging. Works with Cuk, and your custom commands.

Result
Response
Command Result
Run

- Snippet Examples -


Result as File
Filter Like grep
Print Options
No Result Printed
No Parse for Debugging


Tips & Trick

You need to know for optimizing your Cakcuk


Work with Slackbot

You can work with Slackbot to make your Cakcuk powerful.

  1. Creating Slackbot alias to trigger Cakcuk's commands.
  2. Set a reminder to execute a certain command at a certain time.

Authentication Support

Currently, only basic authentication that's supported on a specific option which is --basicAuth, -ba. But you also can implement the other authentication that's able to generate to be header values.

You can explore it easily on API tools like Postman. You can choose what type of auth you use. Then simply get the generated headers. Then you can put those headers values to Cakcuk command request with --header, -h option.