Run start scripts on an instance

Attach start scripts to an instance, and they run each time it starts or restarts, so the instance sets itself up again every time. Use them to install packages again, because a restart clears everything outside the workspace at /home/jovyan. They can also start a background program, such as an app server, since an instance runs without systemd to start services for you. TIR skips a public image’s own start command, so anything the image must run at start goes in a start script. You can attach several scripts to one instance, and attaching them is free.

Before you begin

• A role in the project that lets you update instances, to attach scripts to an existing instance.
• A start script saved in the project, or the commands to put in a new one. Start scripts belong to the project, so one script can run on any of its instances.

Write a start script

On the Create Instance form, under Advanced Settings > Startup Script, select Create a new Script to open the script form. On an existing instance, select Add Script or Modify Script on Network & Security > Start Scripts, then use the link under the list to open it. Enter a Script Name of 3 to 50 letters, digits, hyphens, and underscores. It must start with a letter, end with a letter or digit, and be unique in the project. Write the script in Enter Script, or use Upload file to load a .sh file, whose text replaces the editor’s. Select Save Script.

Write the script as a Bash shell script. On a custom or public image, TIR runs each script with bash, so a first line naming another interpreter, such as Python, is ignored. To run Python, call it from the script instead, for example by running your setup file with python3.

This example installs a system package and a Python package again, then starts an app in the background:

#!/bin/bash
apt-get update
apt-get install -y <apt-package>
pip install --no-cache-dir <python-package>
nohup <command> > /home/jovyan/app.log 2>&1 &

Replace <apt-package> and <python-package> with the packages your work needs, and <command> with the command that starts your program, such as a Python script in /home/jovyan. Run apt-get update before apt-get install: on a custom or public image, apt’s package lists start empty. The last line starts the program in the background with nohup and writes its output to a log file in the workspace, so the script returns and the program keeps running.

Attach scripts when you create an instance

On the Create Instance form, open Advanced Settings. Under Startup Script, pick one or more of the project’s saved scripts. The scripts run when the instance first starts, and again at every start and restart after that.

Attach scripts to an existing instance

1. Open the instance and go to Network & Security > Start Scripts.
2. Select Add Script (or Modify Script when scripts are already attached), and add or remove scripts in the list.
3. Select Update, then Confirm in Confirm Attached Scripts.

On a stopped instance, the scripts run the next time you start it. On a running instance, they run after the instance restarts. To run them now, restart the instance. See Stop, start, and restart an instance. A restart ends every program in the instance, so save your work in /home/jovyan first.

Edit or delete a script

On an instance’s Start Scripts, select Add Script or Modify Script. To edit a script, select Edit Script beside it, change it, and select Save Script, then Confirm in Confirm Script Editing. The change applies to every instance that uses the script, each after its next restart. To delete a script, select Delete Script beside it and Confirm. To delete a script that an instance still uses, detach it from every instance first.

When the scripts run

Start scripts run each time the instance’s container starts:

• when you start the instance
• when you restart it
• when TIR replaces the container for another reason, such as a plan change, an image update, or the instance running out of memory

On a custom or public image, TIR runs the scripts one after another, waiting for each to finish, and starts SSH only after the last one. A script that keeps running in the foreground holds SSH back, so start long-running programs in the background, as the example does. TIR also runs the scripts in its own order there rather than the order you attached them, so put steps that must run in order in one script.

Because the scripts run again on every start, write each one so that running it twice is safe. For example, install a package only when it is missing, and overwrite a settings file rather than adding the same lines to it again.

When you clone an instance, the clone gets the same start scripts.

Start scripts on a pre-built image

On the TensorFlow, Transformers, and Jupyter pre-built images, a start script also runs as root and can write into the workspace at /home/jovyan. Its output appears on the instance’s Logs tab. The instance reaches Running even when a script fails or ends with an error, so check Logs to see whether the script did what you expected.

Check that the scripts ran

After the instance shows Running, connect to it and check what the script set up. For example, if the script installs a Python package, run pip3 show <package-name> in a terminal on the instance, replacing <package-name> with the package. If the script starts a program, check that it is running and answering. On a custom or public image, each script’s output is on the instance’s Logs tab too, after TIR’s line Processing file: /etc/config/initialize-<n>.sh.

To reach a program that a start script runs, see Open a port on an instance. For problems, see Troubleshooting TIR Instances.