Application Tasks - One-Off Containers
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][osc-fr1] 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 one-off container has, by default, access to 512 MiB memory (equivalent to a size M). If your one-off container needs more available memory, you can use the
$ scalingo --app my-app run --size XL /app/my_big_script.sh
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][osc-fr1] Scalingo:my-app ~ $ dbclient-fetcher mongo ---> Download and extract the database CLI [...] [10:45][osc-fr1] 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
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.
--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.
Stop a One-Off
You should make sure the job ends at some point.
If it goes rogue, you can stop it with
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
It displays then a list of all containers including the container name.
scalingo --app my-app ps
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:
$ 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
$ scalingo --app my-app run bash [10:45][osc-fr1] 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
bash with custom environment variables
$ scalingo --app my-app run --env VAR1=VAL1 --env VAR2=VAL2 bash [10:51][osc-fr1] Scalingo ~ $ env | grep VAR VAR1=VAL1 VAR2=VAL2
Upload an archive and extract it on the server
- Use the
--fileflag 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
[10:51][osc-fr1] Scalingo ~ $ ls /tmp/uploads dump.tar
- Extract the archive to
[10:51][osc-fr1] Scalingo ~ $ tar -C /app -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][osc-fr1] 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
$ scalingo --app my-app run bash [10:51][osc-fr1] Scalingo ~ $ install-scalingo-cli -----> Downloading Scalingo client... DONE -----> Extracting... DONE -----> Install scalingo client to /app/bin -----> Installation completed, the command 'scalingo' is available.