{"id":13828709,"url":"https://github.com/jsphpl/laravan","last_synced_at":"2025-07-09T06:32:44.264Z","repository":{"id":29994178,"uuid":"123431356","full_name":"jsphpl/laravan","owner":"jsphpl","description":"Ansible Playbooks for Laravel - machine provisioning and app deployment","archived":true,"fork":false,"pushed_at":"2022-03-29T21:54:44.000Z","size":205,"stargazers_count":72,"open_issues_count":10,"forks_count":17,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-10-31T13:12:18.500Z","etag":null,"topics":["ansible","ansible-playbook","laravel"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jsphpl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-03-01T12:22:05.000Z","updated_at":"2024-10-08T16:54:28.000Z","dependencies_parsed_at":"2022-08-07T15:00:23.402Z","dependency_job_id":null,"html_url":"https://github.com/jsphpl/laravan","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsphpl%2Flaravan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsphpl%2Flaravan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsphpl%2Flaravan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsphpl%2Flaravan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jsphpl","download_url":"https://codeload.github.com/jsphpl/laravan/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225492420,"owners_count":17482869,"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":["ansible","ansible-playbook","laravel"],"created_at":"2024-08-04T09:03:02.721Z","updated_at":"2024-11-20T08:31:01.285Z","avatar_url":"https://github.com/jsphpl.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Laravan\n\n**Ansible Playbooks for Laravel - machine provisioning and app deployment**\n\nLaravan is capable of preparing a fresh Ubuntu 16.04 / 18.04 machine for running laravel apps and docker containers by setting up the following components using Ansible:\n\n- Nginx\n- PHP 7.2, 7.3 \u0026 7.4\n- MariaDB 10\n- PostgreSQL 11\n- Beanstalkd\n- Redis\n\nIt also brings some neat, optional stuff:\n\n- Run services in docker containers and expose them via https through a reverse proxy\n- Single-command deployment of Laravel applications with rollback capability\n- Automatic database backups\n- Free TLS certificates via letsencrypt\n- Supervisor for reliably running queue workers\n- Hosting of static pages and Single Page Applications\n\nThis makes Laravan a viable alternative to paid tools like Forge or Envoyer. It can also be used to implement Continuous Integration/Deployment by running the playbooks from your CI server.\n\n## Table of Contents\n- [Getting Started](#getting-started)\n   - [1. Install Ansible](#1-install-ansible)\n   - [2. Prepare Server](#2-prepare-server)\n   - [3. Install Laravan](#3-install-laravan)\n   - [4. Link Machines](#4-link-machines)\n   - [5. Configure Applications](#5-configure-applications)\n   - [6. Configure Databases](#6-configure-databases)\n   - [7. Encrypt vault](#7-encrypt-vault)\n   - [8. Set ssh keys for web user](#8-set-ssh-keys-for-web-user)\n   - [9. Provision](#9-provision)\n   - [10. Deploy](#10-deploy)\n- [Using laravan in your CI/CD pipeline](#using-laravan-in-your-cicd-pipeline)\n   - [Using laravan with Gitlab Pipelines](#using-laravan-with-gitlab-pipelines)\n- [Credits](#credits)\n- [License](#license)\n\n## Getting Started\n### 1. Install Ansible\nAnsible needs to be installed on your **local machine** from which you're going to provision your servers and deploy your Laravel apps. Install instructions: [http://docs.ansible.com/ansible/latest/intro_installation.html](http://docs.ansible.com/ansible/latest/intro_installation.html)\n\n### 2. Prepare Server\nBoot up a fresh Ubuntu 18.04 machine. Set up ssh keys for the root user and make sure you can log in from your local machine.\n\nThe target machine needs to have `python` (v2) installed in order to be provisioned by Ansible.\n\n#### Vagrant (optional)\nA Vagrantfile is provided with laravan, so you can fire up a fresh local vm by just stating `vagrant up` from your laravan directory. You will still need to set up your ssh keys for the root user of the Vagrant box.\n\n### 3. Install Laravan\nOn your local machine, run the following commands to prepare Laravan:\n\n```bash\ngit clone https://github.com/jsphpl/laravan\ncd laravan\n./setup.sh\n```\n\n### 4. Link Machines\n1. Enter the IP addresses of your hosts to the `hosts` file, each under their respective environment. If you created a vagrant machine using `vagrant up` from the laravan directory, its IP address will be `10.10.0.42`.\n\n### 5. Configure Applications\nOpen up `group_vars/{env}/apps.yml` and provide the necessary information for your Laravel apps. There is an example under `group_vars/production/apps.yml` to get you started.\n\n**Note:** in `apps.yml`, you will need to specify some \"sensitive\" variables that should not be entered into your VCS in plain text, eg. `env.APP_KEY`. In the example, the values reference variables in the vault, eg. `{{ vault.app_key }}`. These variables need to be assigned concrete values in the `group_vars/{env}/vault.yml`. Please refer to section *7. \"Encrypt vault\"* for instructions on how to encrypt your vault files.\n\n- `myapp` (key of the dictionary items) must be replaced with a unique name for the app\n- `canonical:` holds the primary domain name under which your app will be available\n- `env:` those values will eventually be written into an `.env` file on the server\n\n### 6. Configure Databases\nOpen up `group_vars/{env}/databases.yml` and configure the databases required for your apps. There is an example under `group_vars/production/databases.yml` to get you started.\n\n### 7. Encrypt vault\nIn order to prevent your production secrets from ending up as plain text in your git repositories, use the [ansible vault](http://docs.ansible.com/ansible/latest/vault.html).\n\n1. Create a `.vault_pass` file containing a strong password in the project root (eg. `openssl rand -base64 64 \u003e .vault_pass`). This file is gitignored, which you should leave at all cost. Your coworkers who need to be able to provision/deploy as well, will need a copy of the file. *Send it to them by other (encrypted) means, but don't add it to your VCS!*\n2. Encrypt your vault: `ansible-vault encrypt group_vars/production/vault.yml`\n3. **Never again decrypt the vault!**. Use `ansible-vault view \u003cpath\u003e` or `ansible-vault edit \u003cpath\u003e` to open the vault file. This reduces the risk of the vault ending up plain text in your version control.\n\n### 8. Set ssh keys for `web` user\nIn `group_vars/all/users.yml`, make sure to add a valid ssh public key for the `web` user. Either use the `lookup()` syntax to read a local file, or specify a http(s) url for remotely hosted public keys (eg. on github).\n\n### 9. Provision\n**Note: When using \"letsencrypt\" as TLS certificate provider, all domains listed under `canonical` or `redirects` must be mapped to your IP address (resolvable via public DNS) before you can successfully provision your server.**\n\nOn your local machine, run the following command, replacing `production` with the environment you want to provision (most likely `development`, `staging` or `production`).\n\n```bash\nansible-playbook provision.yml -e env=production\n```\n\n### 10. Deploy\nAgain, on the local machine, run the following command to fetch your app from the git repository, install composer dependencies and run the migrations. The `app=myapp` variable refers to a key in the `group_vars/{env}/apps.yml` dictionary.\n\n```bash\nansible-playbook deploy.yml -e env=production -e app=myapp\n```\n\n*Note: Replace `myapp` with the key that your app is listed under in the `apps` object in `group_vars/{env}/apps.yml`. Replace `production` with the environment you want to deploy to*\n\nIn case deployment fails with an error message indicating a lack of access right to the git repository, make sure that a local ssh key is authorized with the git remote of the app. There could also be a problem with with ssh agent-forwarding, which you can troubleshoot using this guide: [https://developer.github.com/v3/guides/using-ssh-agent-forwarding/](https://developer.github.com/v3/guides/using-ssh-agent-forwarding/).\n\n## Using laravan in your CI/CD pipeline\nIn order to use laravan in your CI/CD pipeline, you have to:\n1. Give your CI server access to your laravan repository (with all its configuration in it)\n2. Make the `.vault_pass` available to your CI server\n3. Run the `deploy.yml` playbook in your pipeline in order to deploy the application\n\n### Using laravan with Gitlab Pipelines\nTake a look at [.gitlab-ci.yml.example](.gitlab-ci.yml.example) for an example configuration for Gitlab Pipelines. Make sure to replace all YOUR_xyz_GOES_HERE strings with your actual values.\n\nIn order to make it work, configure the following environment variables in gitlab for the project you're deploying:\n- STAGING_DEPLOY_KEY: *an ssh private key that authorizes the `web` user on your staging system*\n- PRODUCTION_DEPLOY_KEY: *an ssh private key that authorizes the `web` user on your production system*\n- VAULT_PASS: *The vault password to decrypt the ansible vault*\n\nBesides that, make sure:\n- the respective \"DEPLOY_KEYs\" are allowed read access on your application repository and the laravan repository (set them up as deploy keys in the respective Gitlab project)\n- in your `apps.yml` configuration under `source`, set `version: \"{{ lookup('env', 'VERSION') }}\"` in order to deploy the git revision for which the pipeline is running. Otherwise it would default to master and possibly deploy the wrong version.\n\n## Credits\nCredits to the awesome [Trellis](https://github.com/roots/trellis) project, which heavily inspired me to create Laravan and from which i copied some code and concepts.\n\n\n## License\nThis software is released \"as it is\" without any warranty under the MIT licence. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsphpl%2Flaravan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjsphpl%2Flaravan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsphpl%2Flaravan/lists"}