Shell

Shell tasks allow you to write highly customized scripts that run within Airplane. You can use shell tasks to run one-off bash scripts, or even run Ruby scripts within a fully customized environment.
By default, shell tasks run in an Ubuntu-based image. However, with a shell task you can use your own Dockerfile, which opens the door to running different operating systems, custom packages, and custom runtimes.

Getting started

Visit the New Task page to get started.

Define your task

In this first step, you'll be asked to give your task a name and (optional) description.

Parameters

Here, you can define parameters for your task—these parameters will later be based to your code. (See the Parameters documentation for a full reference on what parameters are available.)

Build your task

You'll only define environment variables in this next section. For custom code tasks, the code is deployed separately after the task is created.

Environment variables

Environment variables can be entered directly ("from value"), or you can reference config variables ("from config variable"). Use config variables for secrets and/or values you want to share across multiple tasks.

Configure settings

In this last step, you can optionally configure permissions, timeouts, run constraints, and more. These settings are optional.
That's it! Finish the task creation wizard and you have a shrinkwrapped task for safely running shell scripts.

Deploy your code

By default, Airplane runs your scripts on Ubuntu 21.04.
Once created, the UI will show you instructions on how to init and deploy the task. Your task has a slug, which is a human-readable ID, which you'll need for running the init and deploy commands.
In your own code repository, run airplane init to create a blank task file:
bash
Copied
1
$ airplane init --slug=YOUR_TASK_SLUG
A minimal shell Airplane task looks like this (and gets generated by airplane init):
bash
Copied
1
# your_task_file.sh
2
#!/bin/bash
3
# Linked to https://app.airplane.dev/t/new_shell_task [do not edit this line]
4
5
# Params are in environment variables as PARAM_{SLUG}, e.g. PARAM_USER_ID
6
echo "Hello World!"
7
echo "Printing env for debugging purposes:"
8
env
Airplane executes your script as an executable, looking for the shebang at the top of the file (e.g. #!/bin/bash) to determine how to run the script. Make sure you leave in the Linked to ... line, as this is how the airplane CLI determines which task this file corresponds to.
The parameters you've specified earlier are available as environment variables named after the parameter slug. You can see task slugs when you edit them: for a parameter named User Email, the slug is user_email, and the environment variable is PARAM_USER_EMAIL.

Customize the environment with Dockerfile

By default, Airplane will run your shell script inside an Ubuntu-based image with common tools installed. You may want to customize this if you need a specific operating system, need to install a specific library, etc.
To do this, you can define a custom Dockerfile that Airplane will use to build and configure your environment. Airplane looks for the first file named Dockerfile.airplane in the same directory as your shell script, or in a parent directory. If not found, Airplane will look for a file named Dockerfile instead.
The directory that we find Dockerfile.airplane / Dockerfile in becomes the root directory of your task. Airplane will include all the files in your root directory (minus what is ignored by .airplaneignore) when building your task.
For example, you might have the following layout:
Copied
1
/
2
Dockerfile.airplane
3
prod_tasks/
4
task_a.sh
5
task_b.sh
6
other_tasks/
7
task_c.sh
When running airplane deploy prod_tasks/task_a.sh, Dockerfile.airplane is used to build the image that task_a.sh is run in. By organizing your files like this, you can share the same Dockerfile among multiple tasks.
Airplane will exec the script you deploy, so you should ensure your script is a valid executable. Typically you just need to include a shebang at the top of your file, e.g. #!/bin/bash to run a bash script or even #!/usr/bin/env python to run a Python script:
python
Copied
1
# python_script.py
2
#!/usr/bin/env python
3
print("Hello world!")

Deploy to Airplane

Finally, run deploy to push your script to Airplane:
bash
Copied
1
airplane deploy ./your_task_file.sh
Once deployed, go to the Tasks page to see and run your task!

Examples

Redis

Here's a simple example with an Ubuntu image and Redis, where we'll build a task that runs DEL <key>:
First, let's create a task with a Key parameter:
And ensure you've configured a REDIS_URI environment variable the server host and password:
(Above, we're using a hardcoded value for REDIS_URI. You can also use Config Variables to store secrets.)
Once you've created the task, you can use the following Dockerfile and shell script to connect to Redis and run a command:
Copied
1
# Dockerfile.airplane
2
FROM ubuntu:21.04
3
4
# Install redis-cli via the redis-server package
5
RUN apt-get update -q && apt-get -y install redis-server
bash
Copied
1
#!/bin/bash
2
# Linked to https://app.airplane.dev/t/clear_redis_key [do not edit this line]
3
4
# All you have to do is run redis-cli:
5
redis-cli -u $REDIS_URI del $PARAM_KEY

Ruby

By using a custom Dockerfile, you can set up a full Ruby environment and run Ruby scripts:
Copied
1
# Dockerfile.airplane
2
FROM ruby:2.6
3
4
WORKDIR /app
5
COPY Gemfile /app/Gemfile
6
COPY Gemfile.lock /app/Gemfile.lock
7
RUN bundle install --deployment
8
9
# Assumes there are other files necessary to run your script.
10
COPY . .
And your script might look like this, if you're using Ruby on Rails and wanted to run it via rails runner:
ruby
Copied
1
#!/usr/bin/env -S bundle exec rails runner
2
# Linked to https://app.airplane.dev/t/ruby_on_rails [do not edit this line]
3
4
puts "Running!"
5
article = Article.new(title: "Hello Rails", body: "I am on Rails!")
6
puts "Saving..."
7
article.save