Instruqt Docs
PlatformGithub
Search
⌃K
Links
Comment on page

Customize sandbox hosts

Tune your sandbox hosts.
This guide explains how to customize sandbox hosts.
Sandboxes are hosts for containers and virtual machines. You can configure your containers and virtual machines using scripts. These scripts are called lifecycle scripts because they align with the sandbox lifecycle at these stages:
  • When starting a container or virtual machine, the setup script runs.
  • When stopping a container or virtual machine, the cleanup script runs.
Lifecycle scripts
See the topic Lifecycle scripts for more information.
Things you might want to do from setup and cleanup scripts include:
  • Install your packages and configure them
  • Add files to the container or virtual machine
  • Start additional services
  • Remove packages
You can create scripts with the Web UI and Instruqt CLI. In this guide, you will learn how to:
  • Create a setup script for a container
  • Create a cleanup script for a container

Before you begin

This guide is based on a sandbox with a container. Create a track from a container template if needed.

Create a setup script

First, you will create a setup script that installs an NGINX package in a container during the sandbox startup.
Pick the Web UI or the Instruqt CLI route depending on your preference:
🌐 Web UI
💻 Instruqt CLI
  1. 1.
    Open your browser and go to play.instruqt.com. ↳ Instruqt shows your content.
  2. 2.
    Click the TRACK_NAME of the track where you want to add the setup script. ↳ Instruqt shows the corresponding Track dashboard page.
  3. 3.
    In the Sandbox section, click Scripts.
  4. 4.
    Click setup under the container directory.
  5. 5.
    Insert the following code in the setup script:
    #!/bin/bash
    # This set line ensures that all failures will cause the script to error and exit
    set -euxo pipefail
    ​
    # Here we are installing the nginx package. The noninteractive setting ensures
    # that the apt command won't stop and ask for user input.
    apt -y update
    DEBIAN_FRONTEND=noninteractive apt -y install nginx
    ​
    # Remove the default nginx page and replace it with our own
    rm /var/www/html/index.nginx-debian.html
    ​
    # This cat/EOF trick renders a new index file. This code creates really simple
    # website that shows pictures of cats. Everything between the EOF markers will
    # end up in the /var/www/html/index.html file
    cat >> /var/www/html/index.html <<-EOF
    <html>
    <head><title>Meow!</title></head>
    <body>
    <div style="width:800px;margin: 0 auto">
    <!-- BEGIN -->
    <center><img src="http://placekitten.com/640/480"></img></center>
    <center><h2>Meow World!</h2></center>
    <center>Welcome to the Meow World application. Meow! =^._.^=</center>
    <!-- END -->
    </div>
    </body>
    </html>
    EOF
    ​
    # Start up nginx
    service nginx start
  6. 6.
    Click Save, followed by Back.
  7. 7.
    Click Play track.
  8. 8.
    Click Start to start the challenge.
  9. 9.
    Enter the following command in the terminal:
    service nginx status
    ↳ If you receive the response * nginx is running the setup script was executed correctly.
  1. 1.
    Activate your track directory:
    cd DIRECTORY_NAME
    ⇨ Replace DIRECTORY_NAME with your track directory.
  2. 2.
    Enter the following command to create a new subdirectory called track_scripts:
    mkdir track_scripts
  3. 3.
    Activate the new subdirectory:
    cd track_scripts
  4. 4.
    Open your code editor.
  5. 5.
    Determine your container name. You can find this name in the following ways:
    1. 1.
      Web UI:
      1. 1.
        Click Track details on the Track overview page.
      2. 2.
        Click the Sandbox tab. ↳ Under the subheading Container, you will find the name of your container.
    2. 2.
      Instruqt CLI/Code editor:
      1. 1.
        Open file config.yml. ↳ The property containers: name contains your container name.
  6. 6.
    Create a new file with the name setup-CONTAINER_NAME in the track_scripts subdirectory. You can create the new file with the touch command:
    touch CONTAINER_NAME
    ⇨ Remember to replace CONTAINER_NAME with your container name!
  7. 7.
    Insert the following code into the new file:
    #!/bin/bash
    # This set line ensures that all failures will cause the script to error and exit
    set -euxo pipefail
    ​
    # Here we are installing the nginx package. The noninteractive setting ensures
    # that the apt command won't stop and ask for user input.
    apt -y update
    DEBIAN_FRONTEND=noninteractive apt -y install nginx
    ​
    # Remove the default nginx page and replace it with our own
    rm /var/www/html/index.nginx-debian.html
    ​
    # This cat/EOF trick renders a new index file. This code creates really simple
    # website that shows pictures of cats. Everything between the EOF markers will
    # end up in the /var/www/html/index.html file
    cat >> /var/www/html/index.html <<-EOF
    <html>
    <head><title>Meow!</title></head>
    <body>
    <div style="width:800px;margin: 0 auto">
    <!-- BEGIN -->
    <center><img src="http://placekitten.com/640/480"></img></center>
    <center><h2>Meow World!</h2></center>
    <center>Welcome to the Meow World application. Meow! =^._.^=</center>
    <!-- END -->
    </div>
    </body>
    </html>
    EOF
    ​
    # Start up nginx
    service nginx start
  8. 8.
    Save the new file.
  9. 9.
    Change back into the main track directory:
cd ../
Go back to Instruqt CLI and deploy your track to the Instruqt platform:
instruqt track push
10. Start logging:
instruqt track logs
11. Start the track:
instruqt track open
↳ Your browser opens, showing the Track overview page of your track.
12. Click Start track.
13. Go back to Instruqt CLI and observe the logs. Notice how the setup script runs before you can start the first challenge. Somewhere in your logging, you should see these lines:
... INFO: setup-container: + service nginx start
... INFO: setup-container: * Starting nginx nginx
Setup scripts in production tracks
Setup scripts are best used for final configuration steps and not installing bulky software. Therefore, installing your packages with setup scripts is not recommended for production tracks. Instead, you should create a custom Compute Engine image that ensures fast track startup and fewer runtime dependencies.

Create a cleanup script

Second, you will create a cleanup script that removes the installed NGINX package while closing the sandbox.
🌐 Web UI
💻 Instruqt CLI
  1. 1.
    Open your browser and go to play.instruqt.com. ↳ Instruqt shows your content.
  2. 2.
    Click the TRACK_NAME of the track where you want to add the setup script. ↳ Instruqt shows the corresponding Track dashboard page.
  3. 3.
    In the Sandbox section, click Scripts.
  4. 4.
    Click cleanup under the container directory.
  5. 5.
    Insert the following code in the cleanup script:
    #!/bin/bash
    # This set line ensures that all failures will cause the script to error and exit
    set -euxo pipefail
    ​
    # Stop nginx
    service nginx stop
  6. 6.
    Click Save.
You cannot check if the cleanup script was executed correctly through Web UI. Because this script runs when the track finishes, there is no terminal available anymore to check statuses.
Nevertheless, you can check if the cleanup script was executed by viewing the track logs through Instruqt CLI. To do so, you need to:
  1. 1.
    ​Install Instruqt CLI.
  2. 2.
    ​Pull the track to your machine.
  3. 3.
    View the logging by moving over to the Instruqt CLI route of this section and follow steps 7 to 12.
  1. 1.
    Open your code editor.
  2. 2.
    Determine your container name. You can find this name in the following ways:
    1. 1.
      Web UI:
      1. 1.
        Click Track details on the Track overview page.
      2. 2.
        Click the Sandbox tab. ↳ Under the subheading Container, you will find the name of your container.
    2. 2.
      Instruqt CLI/Code editor:
      1. 1.
        Open file config.yml. ↳ The property containers: name contains your container name.
  3. 3.
    Create a new file with the name cleanup-CONTAINER_NAME in the track_scripts subdirectory. ⇨ Replace CONTAINER_NAME with your container name.
  4. 4.
    Insert the following code into the new file:
    #!/bin/bash
    # This set line ensures that all failures will cause the script to error and exit
    set -euxo pipefail
    ​
    # Stop nginx
    service nginx stop
  5. 5.
    Save the new file.
  6. 6.
    Go back to Instruqt CLI and deploy your track to the Instruqt platform:
    instruqt track push
  7. 7.
    Start logging:
    instruqt track logs
  8. 8.
    Start the track:
    instruqt track open
    ↳ Your browser opens, showing the Track overview page of your track.
  9. 9.
    Click Start track.
  10. 10.
    Finish all the challenges within your track.
  11. 11.
    Click Finish.
  12. 12.
    Go back to Instruqt CLI and observe the track logs. Notice how the cleanup script runs when finishing your track. Somewhere in your log, you should see these lines:
    ... INFO: cleanup-container: + service nginx stop
    ... INFO: cleanup-container: * Stopping nginx nginx
Nice! You are in full control now as you tune Instruqt with scripts.
How-to guides - Previous
Manage sandboxes
Next
Hot start a sandbox
Last modified 4mo ago