{"id":19601503,"url":"https://github.com/stackstorm/st2vagrant","last_synced_at":"2025-04-27T17:32:00.044Z","repository":{"id":44785851,"uuid":"60127987","full_name":"StackStorm/st2vagrant","owner":"StackStorm","description":"Deploy StackStorm event-driven automation platform locally with Vagrant","archived":false,"fork":false,"pushed_at":"2022-01-24T21:03:05.000Z","size":133,"stargazers_count":33,"open_issues_count":1,"forks_count":13,"subscribers_count":24,"default_branch":"master","last_synced_at":"2023-03-22T17:34:52.172Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.stackstorm.com","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/StackStorm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-05-31T22:29:36.000Z","updated_at":"2023-03-22T17:34:52.172Z","dependencies_parsed_at":"2022-09-19T00:30:57.772Z","dependency_job_id":null,"html_url":"https://github.com/StackStorm/st2vagrant","commit_stats":null,"previous_names":[],"tags_count":null,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StackStorm%2Fst2vagrant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StackStorm%2Fst2vagrant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StackStorm%2Fst2vagrant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StackStorm%2Fst2vagrant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StackStorm","download_url":"https://codeload.github.com/StackStorm/st2vagrant/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224076255,"owners_count":17251718,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-11T09:18:42.808Z","updated_at":"2024-11-11T09:18:44.107Z","avatar_url":"https://github.com/StackStorm.png","language":"Shell","readme":"# st2vagrant\n\nSetup [StackStorm](https://www.stackstorm.com/product) (`st2`) on your laptop with Vagrant and\nVirtualBox, so you can play with it locally and develop integration and automation\n[packs](https://docs.stackstorm.com/latest/packs.html).\n\nIf you are fluent with [Vagrant](https://www.vagrantup.com/docs/getting-started), you know where to\nlook and what to do. If you are new to Vagrant, just follow along with step-by-step instructions\nbelow.\n\n\n## Pre-requisites\n* [Install git](https://git-scm.com/downloads) (duh!). You may not have it if you're on Windows.\n\n* Install recent version of [Vagrant](https://www.vagrantup.com/docs/installation/)\n(v1.8.1 at the time of writing). For those unfortunate Windows users: [How to use Vagrant on Windows](http://tech.osteel.me/posts/2015/01/25/how-to-use-vagrant-on-windows.html) may help.\n\n* Install [VirtualBox](https://www.virtualbox.org/wiki/Downloads) (version 5.0 and up), and\nVirtualBox Extension packs ([follow instructions for Extension packs\nhere](https://www.virtualbox.org/manual/ch01.html#intro-installing)).\n\n* Note. Problems have been found using VirtualBox 5.1 with RockyLinux 8, which were resolved\nusing version 6.1. \n\n\n## Simple installation\n\nClone the st2vagrant repo, and start up Vagrant:\n\n```bash\ngit clone https://github.com/StackStorm/st2vagrant.git\ncd st2vagrant\nvagrant up\n```\n\nThis command will download a vagrant box, create a virtual machine, and start a script to provision\nthe most recent unstable version of StackStorm. You will see a lot of text, some of that may be red,\nbut not to worry, it's normal. After a while, you should see a large `ST2 OK`, which means that\ninstallation successful and a VM with StackStorm is ready to play. Log in to VM, and fire some st2\ncommands:\n\n```bash\nvagrant ssh\nst2 --version\nst2 action list\n```\n\nThe WebUI is available at https://192.168.56.20. The default st2admin user credentials are in\n[Vagrantfile](Vagrantfile), usually `st2admin:Ch@ngeMe`.\n\nYou are in business! Go to [QuickStart](https://docs.stackstorm.com/start.html) and follow along.\n\nTo configure ChatOps, review and edit `/opt/stackstorm/chatops/st2chatops.env` configuration file\nto point to Chat Service you are using. See details in \"Setup ChatOps\" section in installation\ndocs for your OS (e.g, [here is one for Ubuntu](https://docs.stackstorm.com/install/rhel7.html#setup-chatops)).\n\nThe Brocade Workflow Composer bits are not yet installed; to add them and get Workflow Designer, RBAC, and LDAP,\nfollow these [instructions to obtain a license key and\ninstall BWC](https://docs.stackstorm.com/install/bwc.html).\n\nIf something went wrong, jump to [Troubleshooting](https://github.com/StackStorm/st2vagrant#common-problems-and-solutions) section below.\n\n\n## Customize your st2 installation\n\nEnvironment variables can be used to enable or disable certain features of the StackStorm installation:\n\n* `RELEASE` - `stable` for the latest stable release, or `unstable` for a current version from dev trunk. DEFAULT: `unstable`\n* `VAGRANT_HOSTNAME` - the hostname to give the VM. DEFAULT: `st2vagrant`\n* `BOX` - the Vagrant base box to use. DEFAULT: `ubuntu/bionic64`\n* `ST2USER` - Username for st2. DEFAULT: st2admin\n* `ST2PASSWORD` - Password for st2. DEFAULT: `Ch@ngeMe`\n* `VERSION` - the version of StackStorm to install: `3.2`\n\nSet the variables by pre-pending them to `vagrant up` command. In the example below, it will install\na version of st2 from development trunc, and set password to `secret`:\n\n```RELEASE=\"unstable\" ST2PASSWORD=\"secret\" vagrant up```\n\nTo evaluate StackStorm on supported OS flavors, consider using the boxes we use\n[for testing `st2`](https://github.com/StackStorm/st2-test-ground/blob/master/Vagrantfile)\nfor best results:\n\n* ubuntu/focal64 for Ubuntu 20.04\n* ubuntu/bionic64 for Ubuntu 18.04 (default)\n* ubuntu/xenial64 for Ubuntu 16.04\n* ubuntu/trusty64 for Ubuntu 14.04\n* bento/centos-6.7 for CentOS 6.7\n* centos/7 for CentOS 7\n* rockylinux/8 for RockyLinux 8\n\nExamples:\n\n```bash\nBOX=\"centos/7\" vagrant up\n```\n\n```bash\nBOX=centos/7 RELEASE=stable vagrant up\n```\n\nOr use your favorite vagrant box. **Note that StackStorm installs from native Linux packages, which\nare built for following OSes only. Make make sure the OS flavor of your box is one of the\nfollowing:**\n\n* Ubuntu 20.04 (Focal Fossa)\n* **Ubuntu 18.04 (Bionic Beaver)** (default)\n* Ubuntu 16.04 (Xenial Xerus)\n* Ubuntu 14.04 (Trusty Tahr)\n\n* CentOS 7 / RHEL 7\n* RockyLinux 8 / RHEL 8 \n\n### Synced folders\n\n**Warning:**\n\nIf you mount the above synced folder prior to ST2 installation, the installation may fail due to\nsynced folders not supporting ownership and/or permissions changes by default.\nAlso, notice that if you enable the above synced folder, it will *hide* the vagrant box's local\n/opt/stackstorm/packs folder. You will need to move the core packages here for ST2 to run properly.\n\nBy the time you read this hint, your VM is most likely already up and running. Not to worry: just\nuncomment the above mentioned line in your `Vagrantfile` and run `vagrant reload --no-provision`.\nThis will restart the VM and apply the new config without running the provision part, so you won't\nreinstall st2. Vagrant will however ask you for your laptop password to sync the folders.\n\nFor details on NFS refer: https://www.vagrantup.com/docs/synced-folders/nfs.html\n\nTo learn about packs and how to work with them, see\n[StackStorm documentation on packs!](https://docs.stackstorm.com/latest/packs.html)\n\n#### Using the vmware_desktop provider\n\nIf you wish to startup a VM with the VMWare Workstation or VMWare Fusionproviders,\neg: vmware_desktop , you will need to specify `SYNCED_FOLDER_OPTIONS=vmware` when\nrunning `vagrant up`.\n\n```\nSYNCED_FOLDER_OPTIONS=vmware BOX=bento/centos-7.6 RELEASE=stable vagrant up\n```\n\nIf you have multiple providers installed, to force the vmwware_desktop provider:\n\n```bash\nVAGRANT_DEFAULT_PROVIDER=vmware_desktop SYNCED_FOLDER_OPTIONS=vmware BOX=bento/centos-7.6 RELEASE=stable vagrant up\n```\n\nOnly the bento/centos-7.6 has been tested. This vagrant box reliably ships with VMWare\ntools installed for synced folders.\n\nThe options to `synced_folder` are the following for the VM provider:\n\n| Provider             | Synced folder options                         |\n| -------------------- | --------------------------------------------- |\n| VMWare               | `**{}` (no options)                           |\n| Virtualbox (default) | `**{nfs: true, mount_options: [\"nfsvers=3\"]}` |\n\n#### Using the libvirt provider (KVM)\n\nIf you want to run the the VM with KVM/libvirt simply do:\n\n``` bash\nBOX=generic/ubuntu1804 vagrant up --provider libvirt\nBOX=centos/7 vagrant up --provider libvirt\nBOX=rockylinux/8 vagrant up --provider libvirt\n```\n\n#### Common synced folders for Pack development\n\nPlaying with StackStorm ranges from creating rules and workflows, to turning your scripts into\nactions, to writing custom sensors. And all of that involves working with files under\n`/opt/stackstorm/packs` on `st2vagrant` VM. One can do it via SSH, but with all your favorite tools\nalready set up on your laptop, it's convenient to hack files and work with `git` there on the host.\n\nYou can create your pack directories under `st2vagrant/` on your host. Vagrant automatically maps\nit's host directory to `/vagrant` directory on the VM, where you can symlink files and dirs to\ndesired locations.\n\nAlternatively, you can specify a comma-separated list of common synced folders in the the\n`SYNCED_FOLDERS` environment variable to mount them in the guest VM.\n\n```bash\nSYNCED_FOLDERS=packs,datastore_load vagrant up\n```\n\nAvailable common synced folders are:\n\n| Host folder        | Guest folder                     |\n| ------------------ | -------------------------------- |\n| `.`                | `/vagrant`                       |\n| `./config`         | `/opt/stackstorm/config`         |\n| `./packs`          | `/opt/stackstorm/packs`          |\n| `./packs_dev`      | `/opt/stackstorm/packs_dev`      |\n| `./datastore_load` | `/opt/stackstorm/datastore_load` |\n\n#### Custom synced folders\n\nIf you would like to use synced folders that are not one of the common synced folders, you can\nspecify a comma-separated list of custom folders to sync in the `CUSTOM_SYNCED_FOLDERS`\nenvironment variable.\n\nThere are different ways to specify synced folders. You can specify just the host folder, which\nwill be mounted to `/home/vagrant/{folder}` within the guest, using the mount settings specified\nwith `SYNCED_FOLDER_OPTIONS`.\n\n```bash\nCUSTOM_SYNCED_FOLDERS=../st2client.js,../hubot-stackstorm vagrant up\n```\n\nwill mean `../st2client.js` and `../hubot-stackstorm` will be mounted into\n`/home/vagrant/st2client.js` and `/home/vagrant/hubot-stackstorm`, respectively, in the guest.\n\nYou can also specify the host folder as well as the guest folder, by separating them with a `:`:\n\n```bash\nCUSTOM_SYNCED_FOLDERS=../st2client.js:/custom/dir/st2client.js,../hubot-stackstorm:/custom/dir/hubot-stackstorm vagrant up\n```\n\nThis will mount the directories into `/custom/dir/st2client.js` and `/custom/dir/hubot-stackstorm`,\nrespectively, using the default mount settings specified with `SYNCED_FOLDER_OPTIONS`.\n\nFinally, you can specify mount options individually for each synced folder by adding them after\nanother `:`:\n\n```bash\nCUSTOM_SYNCED_FOLDERS=../st2client.js:/custom/dir/st2client.js:{disabled:true},../hubot-stackstorm:/custom/dir/hubot-stackstorm:{custom_option:[\"nfsvers=3\"]} vagrant up\n```\n\nThe options will be `eval()`ed (as a Ruby snippet) within the `Vagrantfile`, then used in a double\nsplat argument. This means that you can specify all options to the `vm.synced_folder` function\nin these options.\n\n#### Advanced Pack Development Synced Folder Workflow Strategy\n\nOne of the common use cases is pack development. In order to streamline a persistent local\ndevelopment environment, the following approach could be used:\n\n**Warning**\n\nSyncing the config directory before ST2 install will cause the installation to fail due to permissions. There is\nprobably a workaround -\u003e if you know it open an issue and let us know.  \n\n1. Synced folders you may wish to utilize to speed up setup of Vagrant box:\n    \n    * `config`          --\u003e synced to `/opt/stackstorm/config`\n    * `datastore_load`  --\u003e synced to `/opt/stackstorm/datastore_load`\n    * `packs_dev`       --\u003e synced to `/opt/stackstorm/packs_dev`\n\n2. Folder usage:\n\n    * `config` folder: You can persist pack configs such as `aws.yaml` or `jira.yaml` in this folder and they will be\n    present after vagrant up\n    * `datastore_load`: Use this folder to store a json file that you would import to the datastore using \n    `st2 key load /opt/stackstorm/datastore_load/mykeystoredata.json`\n    * `packs_dev`: Use this folder to iterate on packs you are developing. After you commit your changes you can install\n     the pack in your Vagrant box:\n         - `cd /opt/stackstorm/packs_dev/YOUR_PACK_DIRECTORY`\n         - `st2 pack install file:///$PWD [--python3]` \n         \n 3. Additional information\n \n    * This repo includes .gitignore entries for the 3 directories described above.\n    * This approach remove any installation conflicts, and prevents confusion of installing dev packs into ST2, since\n    the `st2 pack install` command will create a clone of the pack in `/opt/stackstorm/packs` directory.\n\nSee the `NFS Advanced Pack Dev Approach` and `VMWARE HGFS Advanced Pack Dev Approach` in the Vagrantfile for synced \nfolder configs that follow this strategy.\n\n\n## Manual installation\n\nTo master StackStorm and understand how things are wired together, we strongly encourage you to\n[eventually] install StackStorm manually, following\n[installation instructions](https://docs.stackstorm.com/install/). You can still\nbenefit from this Vagrantfile to get the Linux VM up and running: follow instructions to\ninstall Vagrant \u0026 VirtualBox to get a Linux VM, and simply comment out the\n`st2.vm.provision \"shell\"...` section in your `Vagrantfile` before running `vagrant up`.\n\n\n## Common problems and solutions\n\n#### IP Conflicts\n\nIn the event you receive an error related to IP conflict, Edit the `private_neworks` address in `Vagrantfile`, and adjust the third octet to a non-conflicting value. For example:\n\n```\n    # Configure a private network\n    st2.vm.network :private_network, ip: \"192.168.56.20\"\n```\n\n\n#### Mounts\n\nSometimes after editing or adding NFS mounts via `config.vm.synced_folder`,and firing `vagrant up` or `vagrant reload`, you may see this:\n\n```\n==\u003e st2express: Exporting NFS shared folders...\nNFS is reporting that your exports file is invalid. Vagrant does\nthis check before making any changes to the file. Please correct\nthe issues below and execute \"vagrant reload\":\n\nexports:3: path contains non-directory or non-existent components: /Volumes/Repo/st2\nexports:3: path contains non-directory or non-existent components: /Volumes/Repo/st2contrib\nexports:3: path contains non-directory or non-existent components: /Volumes/Repo/st2incubator\nexports:3: no usable directories in export entry\nexports:3: using fallback (marked offline): /Volumes/Repo\n```\nFIX: Remove residuals from `/etc/exports` file on the host machine, and do `vagrant reload` again.\n\n\n## Using st2vagrant for release testing\n\nCreates a box from a specific development version of code:\n\n``` bash\nBOX=centos/7 RELEASE=unstable VERSION=3.1dev vagrant up\n```\n\n## Support\n\nPlease follow [guidelines](https://docs.stackstorm.com/troubleshooting/ask_for_support.html) for support if none of the [self troubleshooting guides](https://docs.stackstorm.com/troubleshooting/index.html) do not help! Ask community on Slack at stackstorm-community.slack.com channel ([register here first](https://stackstorm.com/community-signup)).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackstorm%2Fst2vagrant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstackstorm%2Fst2vagrant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackstorm%2Fst2vagrant/lists"}