Quickstart
This guide will get you up and running using Tower quickly. It uses the publicly available Tower examples as a starting point, and should show you everything you need to know to execute your first app on Tower.
1: Create a Tower account
Visit the Tower Registration page to create a new Tower account, if you haven’t already. During private beta you will need an invitation code to register. Your Tower contact will supply you with one.
2: Install the Tower CLI
The Tower command line interface (CLI) is one of the two main ways that you interact with the Tower system (the other one is the Tower UI). You can install the latest version of the CLI via the following command.
pip install -U tower
You can find other ways to install the Tower CLI in our documentation.
3: Clone the tower-examples repository
You can go to find the repository in Github, which includes instructions on how to download it. Otherwise, simply run the following command to create a clone of the repository.
git clone https://github.com/tower/tower-examples
For this quick start guide, we’ll focus on the hello-world example in the examples repository.
4: Login to Tower
To start using Tower, you need to create a session in the CLI. You can use the tower login command in your CLI to log in. This will open a browser window that helps you with the login process.
tower login
_____ _____ _____ ___
|_ _/ _ \ \ / / __| _ \
| || (_) \ \/\/ /| _|| /
|_| \___/ \_/\_/ |___|_|_\
⠋ Waiting for login...
In the browser enter your Tower credentials or use a social login.
Sometimes a link will be displayed instead of the window opening directly, which you can just copy and paste into your browser.
5: Create a hello-world example app
The examples repository you just cloned includes a simple “Hello, world!” example in the directory 01-hello-world. We’ll use that as the basis for getting started. You’ll need to create an app in your account, though, which Tower will use for executing the example.
You can create an app from the CLI using the following command.
tower apps create --name="hello-world"
If you look at the Towerfile in 01-hello-world, you’ll see that the name corresponds to the name of the app you just created. Whenever you’re executing the CLI inside a directory with a Towerfile, the Tower CLI will automatically infer the name from the context.
cd ./01-hello-world
cat Towerfile
[app]
name = "hello-world"
script = "./task.py"
source = [
"./task.py",
]
[[parameters]]
name = "friend"
description = "Someone that is close to you."
default = "Steve"
[[parameters]]
name = "foe"
description = "Something that you'd prefer to avoid."
default = "Carl"
Another thing to note is that the Towerfile includes a parameters section. This is where you can define parameters that can be used in your Tower application.
6: Deploy your app to Tower
Now that you’ve created the app in Tower, you need to deploy the code for the app to Tower. You can use the tower apps deploy command to do this. Just navigate to the directory in the cloned repository and run tower apps deploy.
cd ./01-hello-world
ls
Towerfile task.py
tower deploy
✔ Building package... Done!
Deploying to Tower... [00:00:00] [████████████████████████████████████████] 3.00 KiB/3.00 KiB (0s)
Success! Version `v1` of your code has been deployed to Tower!
The Tower CLI uses the Towerfile to determine what source code should be packaged for deployment. You can find a complete reference for the Towerfile fields in our documentation here.
All of the code that you deploy to Tower is encrypted. The only place that the code is ever decrypted is in the Tower runner. This means that Tower employees and administrators cannot ever read your code!
In the Tower UI (> Apps) you can see the deployed version of your app.
7: Run your new app
Now that you've deployed your code, you can use the tower run command to execute the application. Tower will create a new runner in the Tower infrastructure, download the latest verison of the code to the runner, and execute the application.
tower run
✔ Scheduling run... Done!
Success! Run #1 for app `hello-world` has been scheduled
You can check on the status of your run using tower apps show. Again, if you do so from a directory with a Towerfile in it, the name of the app is inferred from the Towerfile. You can specify an explicit app name, for example tower apps show hello-world.
tower apps show hello-world
Name: hello-world
Description:
Recent runs:
# Status Start Time Elapsed Time
----------------------------------------------
2 exited 2025-02-18 15:23:50 5s
1 exited 2025-02-18 15:22:15 5s
Each run gets an automatically incrementing run number. In the above example, we've invoked the hello-world app twice so the run number is 2. The run will be complete when the Status field is “exited.” If something goes wrong during the run, the Status field will be “errored.”
In the Tower UI (> Apps > hello-world) you can also see all the information about the hello-world app, including all its runs.
Once the run has exited, you can get the logs from the run using tower apps logs and by supplying the app name and the run number. You have to explicitly specify a run number in this case, therefor inference the app name from a local Towerfile doesn’t work with this command!
tower apps logs hello-world#2
✔ Fetching logs... Done!
2025-02-18 15:23:50 | Hello, Steve! Boo to Carl
2025-02-18 15:23:51 | Hello, Steve! Boo to Carl
2025-02-18 15:23:52 | Hello, Steve! Boo to Carl
2025-02-18 15:23:53 | Hello, Steve! Boo to Carl
2025-02-18 15:23:54 | Hello, Steve! Boo to Carl
You can also see run logs, updated in near real-time, in the Tower UI (> Apps > hello-world > Run #2).
And that's it! Now you have a working Tower application.