thecodinglove-kotlinjs
is a cutting-edge Kotlin multiplatform project, powering TheCodingLove GIFs Slack app. Built with KotlinJS, it seamlessly bridges Kotlin and Javascript to bring a fully serverless platform, currently deployed as a Docker container on Google Cloud using Pulumi infrastructure as code.
🛠 Tech stack
- KotlinJS - NodeJS transpiling
- PubSub - event-driven messaging
- Firestore - NoSQL database
- Docker - containerised deployment
- Cloud Run - serverless deployment of containers
- Cloud Scheduler - cron jobs
- GitHub Actions - CI automation
- Pulumi - infrastructure as code
- nginx - API reverse proxy
The project can be run locally and on the cloud - in this case Google Cloud via Pulumi. The local build is generally independent but it still talks to a Firestore database and sends PubSub messages, so the cloud setup is still required.
1️⃣ Google Cloud setup
- Create a new Google Cloud project.
- Create a Service Account for the infrastructure as code setup with the following roles:
Artifact Registry Administrator
Firebase Admin
Service Account User
Service Usage Admin
Pub/Sub Admin
Cloud Scheduler Admin
- (Optional) If you're specifying a custom domain mapping, as we are, verify domain ownership and add your service account as owner.
- Export a JSON API key for your Service Account and call it
credentials-gcp-infra.json
. - Signup and Install Pulumi.
- Create a Pulumi access token and login locally using
pulumi login
. - Create a new empty folder under the root of the project, called
infra
andcd
into it. - Create an empty Pulumi project with no resources using the
pulumi new
command and follow the instructions:- you can use the prompt
Empty project with no resources
for Pulumi AI - you can use
prod
as your stack name
- you can use the prompt
- Replace the created
Pulumi.yaml
file with the one from the existingpulumi
folder, preserving the originalname
and paste the Service Account JSON API key file there too. - Setup Pulumi with your Google Cloud project ID and credentials:
pulumi config set gcp:credentials credentials-gcp-infra.json
pulumi config set gcp:project GCP_PROJECT_ID
- Run
pulumi up
to automatically create the required project infrastructure. - Find your new
firebase-adminsdk
Service Account and give it the following additional roles:
Pub/Sub Publisher
, for publishing messages to PubSub topics
- Export a JSON API key for your
firebase-adminsdk
Service Account and call itcredentials-gcp-app.json
- the app will need it later.
2️⃣ Slack setup
The project powers an existing Slack app, so you'll need one in order to run it.
- Create a new Slack app.
- You will need an SSH tunnel to your localhost for Slack's APIs. You can use serveo.net for free and configure it with this command
ssh -R YOUR_DOMAIN.serveo.net:80:localhost:3000 serveo.net
. - Point the following Slack features to the relevant project APIs that know how to respond to them using the url you used for serveo.net:
- Slash commands ->
YOUR_DOMAIN.serveo.net/api/slack/slash
- OAuth ->
YOUR_DOMAIN.serveo.net/api/slack/auth
- Events ->
YOUR_DOMAIN.serveo.net/api/slack/event
- Interactivity ->
YOUR_DOMAIN.serveo.net/api/slack/interactivity
- Slash commands ->
- Note down your
Slack Client ID
,Secret
andSigning Secret
.
3️⃣ Local setup
- Install Docker Desktop and start it up. No additional configuration is required as the project uses Docker Compose to run locally. Checkout the
docker
folder for the setup. - Install IntelliJ. This project has been tested with
IntelliJ IDEA 2023.2.5
. - Clone the repository and open the project with IntelliJ.
- Create a Slack channel to receive server error messages and monitoring updates. The project is configured to post all unhandled
Throwable
s to that channel. We use the Incoming Webhooks app. - Create a
env.properties
file at the root of the project with the following contents:
SLACK_SIGNING_SECRET=YOUR_SLACK_SIGNING_SECRET
SLACK_REQUEST_VERIFICATION_ENABLED=true|false
SLACK_CLIENT_ID=YOUR_SLACK_CLIENT_ID
SLACK_CLIENT_SECRET=YOUR_SLACK_CLIENT_SECRET
SLACK_INTERACTIVITY_PUBSUB_TOPIC=TOPIC_NAME
SLACK_SLASH_COMMAND_PUBSUB_TOPIC=TOPIC_NAME
SLACK_MONITORING_URL=YOUR_SLACK_MONITORING_URL
SEARCH_PRELOAD_PUBSUB_TOPIC=TOPIC_NAME
- Copy the
credentials-gcp-app.json
Service Account JSON API key to the root project folder.
After completing the setup, you should be able to run the project locally using the TheCodingLove-Docker
IntelliJ IDE configuration. There is a landing page that should be available when you navigate to your serveo.net url.
This is really up to you! However, we've provided our setup below.
GitHub Actions
The project is configured to build with GitHub Actions. Checkout the .github
folder for the workflows. Follow these steps to configure the CI environment:
- Add your Pulumi access token as a GitHub encrypted secret with the name
PULUMI_ACCESS_TOKEN
. - Each of the variables defined in
env.properties
above should be exposed as GitHub encrypted secrets under the same names. - Add an additional
GCP_SA_KEY_INFRA
GitHub encrypted secret, containing the raw JSON API key for the above infrastructure as code Service Account. - Add an additional
GCP_SA_KEY_APP
GitHub encrypted secret, containing the raw JSON API key for thefirebase-adminsdk
Service Account. - (Optional) Install the Pulumi GitHub app to get automated summaries of your infrastructure as code changes directly on your PR.
Once this is done:
- opening pull requests against the repo will trigger build/test checks as well as infrastructure changes preview
- merging pull requests to the main branch deploys the app and any infrastructure changes to Google Cloud