Killswitch
🪆 Killswitch is a clever control panel that allows mobile developers to apply runtime version-specific behaviors to their iOS or Android application.
Install / Use
/learn @mirego/KillswitchREADME
| Section | Description | | --------------------------------------- | ------------------------------------------------------ | | 🚧 Dependencies | Technical dependencies and how to install them | | 🏎 Kickstart | Details on how to kickstart development on the project | | 🏇 Usage | Details on how to use the application | | 🚑 Troubleshooting | Recurring problems and proven solutions | | 🚀 Deploy | Deployment instructions |
🚧 Dependencies
Every runtime dependencies are defined in the .tool-versions file. These external dependencies are also required:
- PostgreSQL (
~> 10.0)
🏎 Kickstart
Environment variables
All required environment variables are documented in .env.dev.
When running rails, rake or make commands, it is important that these variables are present in the environment. There are several ways to achieve this. Using nv is recommended since it works out of the box with .env.* files.
Initial setup
- Create both
.env.dev.localand.env.test.localfrom empty values in.env.devand.env.test - Install Ruby and NPM dependencies with
make dependencies - Generate values for mandatory secrets in
.env.devwithrake secret
Then, with variables from .env.dev and .env.dev.local present in the environment:
- Create and migrate the database with
rake db:setup - Start the Rails server with
rails s
Sample data
You can use the sample_data:create Rake task to create an organization, an admin user and a few applications.
$ KILLSWITCH_SAMPLE_DATA_EMAIL=foo@example.com KILLSWITCH_SAMPLE_DATA_PASSWORD=p@ssw0rd rake sample_data:create
make commands
A Makefile is present at the root and expose common tasks. The list of these commands is available with make help.
Tests
Tests can be ran with make test.
Linting
Several linting and formatting tools can be ran to ensure coding style consistency:
make lintensures code follows our guidelines and best practicesmake formatformats files using Prettier
Continuous integration
The .github/workflows/ci.yaml workflow ensures that the codebase is in good shape on each pull request and branch push.
🏇 Usage
HTTP requests
Request a behavior
GET /killswitch
Parameters
| Field | Type | Description |
| --------- | ------ | -------------------------------------------------------------------------------------------- |
| key | String | The API key (eg. "f206934e29160b43924308251b88") |
| version | String | The version of the application to test against (see Conventions → Version numbers section) |
Headers
| Header | Description |
| ----------------- | ---------------------------------------------------------------------------------------------------------- |
| Accept-Language | The application language (the API will return localized messages, if available (eg. Accept-Language: fr) |
Possible erroneous responses
| Status | Code | Reason |
| ------ | ----------- | ----------------------------------------------------- |
| 400 | Bad Request | Parameters are malformed or missing |
| 404 | Not Found | The API key is not for a valid project or application |
Possible successful responses
| Status | Code | Message |
| ------ | ------------ | --------------------------------------------------------------------------------------------------------------- |
| 200 | OK | Everything is under control, yay |
| 304 | Not Modified | If an If-None-Match header is passed and a cached response exist, a 304 will be returned with an empty body |
Conventions
Version numbers
Version numbers supported by Killswitch must match the following regular expression:
/^\d+(\.\d+)?(\.\d+)?(\.\w+)?$/
Here are some valid and invalid version number examples:
| Version number | Valid |
| -------------- | ------------------ |
| 1 | :white_check_mark: |
| 1.2 | :white_check_mark: |
| 1.2.3 | :white_check_mark: |
| 1.2.3.4 | :white_check_mark: |
| 1.2.3.foo | :white_check_mark: |
| foo | :x: |
| 1. | :x: |
| 1.2. | :x: |
| 1.2.3.4.5 | :x: |
Behaviors JSON representations
Root element
| Key | Type | Description |
| --------- | ------ | ------------------------------------------------------------------------- |
| action | String | The action the application should enforce ("ok", "alert" or "kill") |
| message | String | A message to display to the user |
| buttons | Array | An array of buttons to show to the user |
Buttons
| Key | Type | Description |
| ------- | ------ | ---------------------------------------------------------------------------------------------- |
| type | String | The type of button ("cancel, "url" or "reload"), defaults to "cancel" if not specified |
| label | String | The button label |
| url | String | The button URL, if the type is "url" |
Examples
OK
{
"action": "ok",
"buttons": []
}
Alert
{
"action": "alert",
"message": "SUP?",
"buttons": [
{
"type": "cancel",
"label": "Nothing"
}
]
}
Kill
{
"action": "kill",
"message": "The app will be killed now. Please upgrade to the latest version.",
"buttons": [
{
"type": "url",
"label": "Upgrade",
"url": "itms://foo"
},
{
"type": "cancel",
"label": "I don’t want to."
}
]
}
🚑 Troubleshooting
System readiness
The project exposes a GET /ping route that sends an HTTP 200 OK response as soon as the server is ready to accept requests. The response also contains the project version for debugging purpose.
System health
The project exposes a GET /health route that contains checks to make sure the application and its external dependencies are healthy.
| Name | Description |
| ---------- | ------------------------------------------ |
| noop | This check is always healthy |
| database | Check if the database connection is active |
🚀 Deploy
Container
A Docker image can be created with make build and pushed to a registry with make push.
Official Docker images can be pulled from GitHub Container registry. For example, to get the latest main image:
$ docker pull ghcr.io/mirego/killswitch:latest
License
Killswitch is © 2013-2025 Mirego and may be freely distributed under the New BSD license. See the LICENSE.md file.
The shield logo is based on this lovely icon by Kimmi Studio, from The Noun Project. Used under a Creative Commons BY 3.0 license.
About Mirego
Mirego is a team of passionate people who believe that work is a place where you can innovate and have fun. We’re a team of talented people who imagine and build beautiful Web and mobile applications. We come together to share ideas and [change the world](http://www.mi
