Application Tasks - One-Off Containers

Introduction

When your app is deployed on our infrastructure, the Procfile of your project is analyzed and the different way to start your project are registered and are available for scaling in your dashboard.

For various reasons you may need to run other tasks in the environment of your application (a database migration, Rails console, rake tasks, etc.). In such case, Scalingo lets you run a task on a copy of your production environment.

If you’re looking to execute scheduled tasks, you’d better read this page.

Run an Attached One-Off

You may want to browse the files of your deployed application or execute a simple task. This is achieved with the following command:

$ scalingo --app my-app run bash
[10:45] Scalingo:my-app ~ $ ls
app.js  cron.js  node_modules  package.json  package-lock.json  Procfile  public  README.md  scalingo.json  views

A one-off container is a copy of your production environment. After the execution of the task, the environment is destroyed. Thus, do not expect any created file to show up in your production environment. The production environment is immutable.

A copy of your production environment means that you can access to the same environment variables in the one-off and in the production. For example, you can connect to your production database with the following commands:

$ scalingo --app my-app run bash
[10:45] Scalingo:my-app ~ $ dbclient-fetcher mongo
---> Download and extract the database CLI
[...]
[10:45] Scalingo:my-app ~ $ mongo $SCALINGO_MONGO_URL

You can also add a shell script that is executed at each start of a new one-off. You need to name it .bashrc and place it at the root of your application.

Note that one-off containers are automatically killed after one hour of inactivity. In this context, inactivity means that nothing is written on standard out or standard error. If you know that your one-off executes a script which lasts for more than an hour, make sure that it regularly writes on standard out or error to prevent it to be killed.

Run a Detached One-Off

By default, one-off containers are started as attached command, it means it will only get started when a terminal interactively connect to it through the one-off endpoint. Once attached, data should be sent to the one-off or from it, otherwise the connection will be automatically closed after 30 minutes and the container will be stopped. For long interactive jobs, make sure the process is writing something to stdout or stderr.

If the --detached option is set, the container will be started as a background one-off container. In this case the container is started instantly, logs from the job are aggregated to the total logs of the application.

Note that the option --file is incompatible with detached one-off.

A detached one-off is not stopped by the platform after 30 minutes of inactivity. Be sure that the detached one-off container will not execute indefinitely, or ensure it is stopped with the scalingo one-off-stop command.

Stop a One-Off

You should make sure the job ends at some point. If it goes rogue, you can stop it with one-off-stop command.

scalingo --app my-app one-off-stop one-off-1234

List all One-Offs

To figure out which containers (including attached and detached one-offs) are running, you can use the ps command. It displays then a list of all containers including the container name.

scalingo --app my-app ps

Audit Logs

For a good traceability of all actions done to your application, we record all actions done in your one-off containers: both the input and the output of the executed commands. These logs are stored encrypted and are decrypted on the fly when displayed. They are available in the Timeline section of the web dashboard:

Examples

Execute a `shell command`

$ scalingo --app my-app run ls
app  bin  config  config.ru  db  Gemfile  Gemfile.lock  lib  log  Procfile  public  Rakefile  test  tmp  vendor

Don’t forget to quote command argument:

$ scalingo --app my-app run 'ls -l'
total 40
drwxrwxr-x 1 appsdeck appsdeck    84 Sep 23 07:42 app
drwxrwxr-x 1 appsdeck appsdeck   114 Sep 23 07:42 bin
drwxrwxr-x 1 appsdeck appsdeck   226 Sep 23 07:42 config
-rw-rw-r-- 1 appsdeck appsdeck   154 Sep 23 07:42 config.ru
drwxrwxr-x 1 appsdeck appsdeck    48 Sep 23 07:42 db
-rw-rw-r-- 1 appsdeck appsdeck  2208 Sep 23 07:42 Gemfile
-rw-rw-r-- 1 appsdeck appsdeck 11085 Sep 23 07:42 Gemfile.lock
drwxrwxr-x 1 appsdeck appsdeck    40 Sep 23 07:42 lib
drwxrwxr-x 1 appsdeck appsdeck    38 Sep 23 07:42 log
-rw-rw-r-- 1 appsdeck appsdeck   137 Sep 23 07:42 Procfile
drwxrwxr-x 1 appsdeck appsdeck   220 Sep 23 07:42 public
-rw-rw-r-- 1 appsdeck appsdeck   249 Sep 23 07:42 Rakefile
drwxrwxr-x 1 appsdeck appsdeck   128 Sep 23 07:42 test
drwxrwxr-x 1 appsdeck appsdeck    76 Sep 23 07:43 tmp
drwxrwxr-x 1 appsdeck appsdeck    56 Nov 13  2014 vendor

Execute `bash`

$ scalingo --app my-app run bash
[10:45] Scalingo ~ $ ls
bin  Godeps  main.go  Procfile  README.md  templates

Connecting to the database

You can use the script dbclient-fetcher to download and install it. Using this script is as simple as:

[10:48] Scalingo ~ $ dbclient-fetcher mongo
---> Download and extract the database CLI
---> Database CLI installed:
MongoDB shell version: 3.4.9

If you ever need a specific version, just add it as a second parameter:

[10:48] Scalingo ~ $ dbclient-fetcher mongo 3.2
---> Download and extract the database CLI
---> Database CLI installed:
MongoDB shell version: 3.2.17

Execute `bash` with custom environment variables

$ scalingo --app my-app run --env VAR1=VAL1 --env VAR2=VAL2 bash
[10:51] Scalingo ~ $ env | grep VAR
VAR1=VAL1
VAR2=VAL2

Upload an archive and extract it on the server

Use the --file flag to select the files to upload

$ scalingo --app my-app run --file ./dump.tar bash
Upload /tmp/job-file635294589/dump.tar to container.

Uploaded files are located in the directory /tmp/uploads

[10:51] Scalingo ~ $ ls /tmp/uploads
dump.tar

Extract the archive to /tmp

[10:51] Scalingo ~ $ tar -C /tmp -xvf /tmp/uploads/dump.tar
/tmp/dump
/tmp/dump/collection1.bson
/tmp/dump/collection1.metadata.json
/tmp/dump/collection2.bson
/tmp/dump/collection2.metadata.json
/tmp/dump/system.indexes.bson
/tmp/dump/system.users.bson
/tmp/dump/system.users.metadata.json

Use these files with a script

[10:51] Scalingo ~ $ /app/script.sh /tmp/dump/*.json

Install the Scalingo CLI

In order to install the Scalingo CLI you need to start an attached one-off and execute the install-scalingo-cli script:

$ scalingo --app my-app run bash
[10:51] Scalingo ~ $ install-scalingo-cli
-----> Downloading Scalingo client...  DONE
-----> Extracting...   DONE
-----> Install scalingo client to /app/bin
-----> Installation completed, the command 'scalingo' is available.

Suggest edits