Getting started | scotty | Spatie SPATIE Scotty ========= spatie.be/open-source [Docs](https://spatie.be/docs) [Scotty](https://spatie.be/docs/scotty/v1) Getting started Version v1 Other versions for crawler [v1](https://spatie.be/docs/scotty/v1) Getting started - [ Introduction ](https://spatie.be/docs/scotty/v1/introduction) - [ Support us ](https://spatie.be/docs/scotty/v1/support-us) - [ Getting started ](https://spatie.be/docs/scotty/v1/getting-started) - [ Requirements ](https://spatie.be/docs/scotty/v1/requirements) - [ Installation & setup ](https://spatie.be/docs/scotty/v1/installation) - [ Questions and issues ](https://spatie.be/docs/scotty/v1/questions-issues) - [ Changelog ](https://spatie.be/docs/scotty/v1/changelog) - [ About us ](https://spatie.be/docs/scotty/v1/about-us) Basic Usage ----------- - [ Your first deploy script ](https://spatie.be/docs/scotty/v1/basic-usage/your-first-deploy-script) - [ The Scotty.sh format ](https://spatie.be/docs/scotty/v1/basic-usage/bash-format) - [ Running tasks ](https://spatie.be/docs/scotty/v1/basic-usage/running-tasks) Advanced Usage -------------- - [ Doctor ](https://spatie.be/docs/scotty/v1/advanced-usage/doctor) - [ File lookup order ](https://spatie.be/docs/scotty/v1/advanced-usage/file-lookup-order) - [ Envoy compatibility ](https://spatie.be/docs/scotty/v1/advanced-usage/envoy-compatibility) - [ Zero-downtime deployments ](https://spatie.be/docs/scotty/v1/advanced-usage/zero-downtime-deployments) Getting started =============== ### On this page 1. [ Prerequisites ](#content-prerequisites) 2. [ Create a Scotty file ](#content-create-a-scotty-file) 3. [ Add your first task ](#content-add-your-first-task) 4. [ Run it ](#content-run-it) 5. [ Add a deploy task ](#content-add-a-deploy-task) 6. [ Group tasks into a macro ](#content-group-tasks-into-a-macro) 7. [ Verify your setup ](#content-verify-your-setup) 8. [ The complete file ](#content-the-complete-file) 9. [ Next steps ](#content-next-steps) Let's get Scotty up and running. By the end of this page, you'll have created a Scotty file and run your first task on a remote server. Prerequisites ----------------------------------------------------------------------------------------------- You'll need [Scotty installed](/docs/scotty/v1/installation) and SSH access (with key-based authentication) to a server you want to run commands on. Create a Scotty file -------------------------------------------------------------------------------------------------------------------- In your project root, run: ``` scotty init ``` Choose the bash format when prompted and enter your server's SSH connection string (for example `deployer@your-server.com`). Scotty creates a `Scotty.sh` file for you. You can also create the file by hand. Just add a `Scotty.sh` in your project root: ``` #!/usr/bin/env scotty # @servers remote=deployer@your-server.com ``` Replace `deployer@your-server.com` with your actual server. Add your first task ----------------------------------------------------------------------------------------------------------------- A task is a bash function with a `# @task` annotation above it. The `on:` parameter tells Scotty which server to run it on. Let's add a simple task that checks the server's uptime: ``` #!/usr/bin/env scotty # @servers remote=deployer@your-server.com # @task on:remote checkUptime() { uptime df -h / } ``` Run it -------------------------------------------------------------------------- ``` scotty run checkUptime ``` Scotty connects to your server over SSH, runs the commands, and streams the output back. That's your first manual SSH step, automated. Add a deploy task ----------------------------------------------------------------------------------------------------------- Now let's add something more useful. Say you have a Laravel app at `/var/www/my-app` on the server: ``` #!/usr/bin/env scotty # @servers remote=deployer@your-server.com # @task on:remote checkUptime() { uptime df -h / } # @task on:remote pullCode() { cd /var/www/my-app git pull origin main } # @task on:remote clearCache() { cd /var/www/my-app php artisan cache:clear php artisan config:clear php artisan view:clear } ``` You can run each one individually with `scotty run pullCode` or `scotty run clearCache`. Group tasks into a macro -------------------------------------------------------------------------------------------------------------------------------- Running tasks one by one isn't much better than doing it by hand. A macro lets you run them in sequence with a single command. Add this near the top of your file, right after the `# @servers` line: ``` # @macro deploy pullCode clearCache ``` Now: ``` scotty run deploy ``` If any task fails, Scotty stops right there so you can investigate. You'll see a summary table at the end with timing for each step. Verify your setup ----------------------------------------------------------------------------------------------------------- Before running a deploy for real, use the doctor command to check that everything looks good: ``` scotty doctor ``` This validates your Scotty file, tests SSH connectivity, and checks that tools like PHP, Composer, and Git are available on the server. The complete file ----------------------------------------------------------------------------------------------------------- Here's what your `Scotty.sh` looks like now: ``` #!/usr/bin/env scotty # @servers remote=deployer@your-server.com # @macro deploy pullCode clearCache # @task on:remote checkUptime() { uptime df -h / } # @task on:remote pullCode() { cd /var/www/my-app git pull origin main } # @task on:remote clearCache() { cd /var/www/my-app php artisan cache:clear php artisan config:clear php artisan view:clear } ``` Next steps -------------------------------------------------------------------------------------- - Learn the full [Scotty.sh format](/docs/scotty/v1/basic-usage/bash-format) with variables, parallel execution, hooks, and more - Already using Envoy? See the [Envoy compatibility](/docs/scotty/v1/advanced-usage/envoy-compatibility) page - Check out how to [run tasks](/docs/scotty/v1/basic-usage/running-tasks) with pretend mode, summary mode, and more A good match? ------------- ### What we do best - All things Laravel - Custom frontend components - Building APIs - AI-powered features - Simplifying things - Clean solutions - Integrating services ### Not our cup of tea - WordPress themes - Cutting corners - Free mockups to win a job - "Just execute the briefing" In short: we'd like to be a **substantial part** of your project. [ Get in touch via email ](mailto:info@spatie.be?subject=A%20good%20match%21&body=Tell%20us%20as%20much%20as%20you%20can%20about%0A-%20your%20online%20project%0A-%20your%20planning%0A-%20your%20budget%0A-%20%E2%80%A6%0A%0AAnything%20that%20helps%20us%20to%20start%20straightforward%21)