agaric/agaric-coop
10
1
Fork 0
Code Issues102 Pull requests Projects Releases Packages Wiki Activity

Add all files needed to bring up VM and run agaric.com locally

Browse source
This commit is contained in:
benjamin melançon 2018-08-20 10:45:20 -04:00
parent 52c8b60bac
commit 4d2bc0ee24
742 changed files with 24037 additions and 0 deletions

48
box/docs/getting-started/configure-drupalvm.md Normal file
View file

@ -0,0 +1,48 @@
If you only need a simple Drupal VM environment up and running there are no required configurations. The [configurations used by default are listed in `default.config.yml`](https://github.com/geerlingguy/drupal-vm/blob/master/default.config.yml) and you can override them with a number of optional configuration files.
_Note: The merge of variables in these files is shallow, if you want to override a single item in a list, you will need to re-define all items in that list._
Configurations files are read in the following order:
#### 1. default.config.yml
Drupal VM's default configurations which you should not edit directly.
#### 2. config.yml
The main configuration file of a project. Commonly this is a copy of `default.config.yml` with the values tweaked to your own project. For an easier upgrade path you would only set the values you are actually overriding.
```yaml
vagrant_box: geerlingguy/centos7
vagrant_hostname: my-custom-site.dev
vagrant_machine_name: my_custom_site
php_version: "5.6"
```
#### 3. vagrant.config.yml
Environment specific overrides. When you run Drupal VM through _Vagrant_, the environment will be set to `vagrant` and this file is loaded when available. If you're doing something more advanced, such as running Drupal VM on a [production environment](../other/production.md), you can use a different environment configuration file, eg `prod.config.yml`.
_Note: In addition to the variables listed in `default.config.yml`, you can also override the variables set by any of the ansible roles. In the "Installed extras" section of this documentation, each role has a link to the available variables._
#### 4. local.config.yml
Local development overrides. Commonly this file is ignored from VCS so that each team member can make local customizations.
```yaml
# Increase the memory available to your Drupal site.
vagrant_memory: 1536
php_memory_limit: "512M"
# Override the synced folders to use rsync instead of NFS.
vagrant_synced_folders:
- local_path: .
destination: /var/www/drupalvm
type: rsync
create: true
```
## Additional resources
- Jeff Geerling's DrupalDC talk "[Drupal VM Tips and Tricks for Drupal 8 development](https://www.youtube.com/watch?v=_wV6MDsT42Y)"

78
box/docs/getting-started/installation-linux.md Normal file
View file

@ -0,0 +1,78 @@
Please read through the [Quick Start Guiden the README](https://github.com/geerlingguy/drupal-vm#quick-start-guide) to get started.
For a quick introduction to setting up Drupal VM, the [macOS video tutorial](installation-macos.md) applies somwhat to Linux as well.
There are a few caveats when using Drupal VM on Linux, and this page will try to identify the main gotchas or optimization tips for those wishing to use Drupal VM on a Linux host.
## Platform-specific Install Instructions
Always make sure your workstation is up to date (e.g. `apt-get update && apt-get upgrade` on Debian-like systems, or `dnf upgrade` or `yum upgrade` on Fedora/RedHat-like systems). There are sometimes bugs in the base OS packages (e.g. [this NFS-related bug](https://bugs.launchpad.net/ubuntu/+source/linux/+bug/1508510)) that can be resolved by a simple upgrade.
### Ubuntu
Ubuntu 15.10 for Desktop (and some other versions) doesn't include NFS support by default, so if you get a message like `It appears your machine doesn't support NFS`, then you should do the following to install NFS server: `sudo apt-get install -y nfs-server`.
### Fedora
Under Fedora, you might encounter a message like the following upon the first time you use VirtualBox or Vagrant:
```
$ vagrant status
VirtualBox is complaining that the kernel module is not loaded. Please
run `VBoxManage --version` or open the VirtualBox GUI to see the error
message which should contain instructions on how to fix this error.
```
In this case, you need to install your system's appropriate kernel module, and you'll also need to install `gcc` and run a specific VirtualBox installation script (or reinstall VirtualBox entirely) so the kernel module is loaded correctly. Do the following:
1. `sudo dnf install "kernel-devel-uname-r == $(uname -r)"`
2. `sudo dnf install gcc`
3. `sudo /var/lib/vboxdrv.sh setup`
Periodically, when you upgrade your system's Linux kernel, you might need to run steps 2 and 3 above again, or you can uninstall and reinstall VirtualBox (e.g. `sudo dnf remove VirtualBox && sudo dnf install VirtualBox`).
### Arch Linux
Arch Linux uses Python 3 as the default while Ansible requires Python 2. To get around parse errors you need to specify that the `python2` binary should be used instead of the default `python`. Add the following to your `config.yml`:
```
ansible_python_interpreter: "/usr/bin/env python2"
```
## Troubleshooting Vagrant Synced Folders
Most issues have to do synced folders. These are the most common ones:
### 'Mounting NFS shared folders...' hangs
There are a few different reasons this particular problem can occur. You may run into the error below during `vagrant up`:
```
The following SSH command responded with a non-zero exit status.
Vagrant assumes that this means the command failed!
mount -o '' 192.168.88.1:'/Users/myusername/Sites/drupalvm' /var/www/drupalvm
Stdout from the command:
Stderr from the command:
stdin: is not a tty
mount.nfs: Connection timed out
```
If the directory you are trying to mount is within an encrypted folder or volume, NFS will very often fail with the above message as well as `exportfs: /home/myusername/Sites/drupalvm does not support NFS export`. There is no workaround other than sharing a directory that is not encrypted.
If encryption is not the issue then it's likely that either NFS isn't running correctly on your host, certain ports or protocols are being blocked by the system firewall, or you need to add additional mount options to your `vagrant_synced_folders` configuration. Try the following fixes:
1. On Ubuntu, if you get a message like `It appears your machine doesn't support NFS`, run `sudo apt-get install -y nfs-server`.
1. Make sure the `vboxnet` interfaces are not being blocked by your system firewall. For Fedora (and many flavors of Linux), check out this guide for more: [Get Vagrant's NFS working under Fedora 20](https://web.archive.org/web/20150706105420/http://blog.bak1an.so/blog/2014/03/23/fedora-vagrant-nfs/).
1. Add `mount_options: ['vers=3']` to your synced folder definition in config.yml after the other options like `local_path`, `destination`, and `type`.
After attempting any of the above fixes, run `vagrant reload --provision` to restart the VM and attempt mounting the synced folder again, or `vagrant destroy -f && vagrant up` to rebuild the VM from scratch.
## Intel VT-x virtualization support
On some laptops, Intel VT-x virtualization (which is built into most modern Intel processors) is enabled by default. This allows VirtualBox to run virtual machines efficiently using the CPU itself instead of software CPU emulation. If you get a message like "VT-x is disabled in the bios for both all cpu modes" or something similar, you may need to enter your computer's BIOS or UEFI settings and enable this virtualization support.

5
box/docs/getting-started/installation-macos.md Normal file
View file

@ -0,0 +1,5 @@
Please read through the [Quick Start Guide](https://github.com/geerlingguy/drupal-vm#quick-start-guide) to get started.
<iframe width="560" height="315" src="https://www.youtube.com/embed/PR9uh_GGZhI" frameborder="0" allowfullscreen></iframe>
_In this quick overview, Jeff Geerling will show you where you can learn more about Drupal VM, then show you a simple Drupal VM setup._

77
box/docs/getting-started/installation-windows.md Normal file
View file

@ -0,0 +1,77 @@
Please read through the [Quick Start Guide in the README](https://github.com/geerlingguy/drupal-vm#quick-start-guide) to get started.
<iframe width="560" height="315" src="https://www.youtube.com/embed/mNio_aXMLos" frameborder="0" allowfullscreen></iframe>
_In this video, Jeff Geerling walk you through getting a Drupal 8 website built on your Windows 10 laptop using Drupal VM 3._
There are a few caveats when using Drupal VM on Windows, and this page will try to identify the main gotchas or optimization tips for those wishing to use Drupal VM on a Windows host.
## Windows Subsystem for Linux / Ubuntu bash
If you are running Windows 10 (Anniversary edition) or later, you can install the Windows Subsytem for Linux, which allows you to install an Ubuntu-based CLI inside of Windows. With this installed, you can then manage and run Drupal VM inside the Linux-like environment. Follow these steps to use Drupal VM in the WSL:
1. Install Vagrant and VirtualBox in Windows (links in the [Drupal VM Quick Start Guide](https://github.com/geerlingguy/drupal-vm#quick-start-guide)).
2. [Install/Enable the Windows Subsystem for Linux](https://msdn.microsoft.com/en-us/commandline/wsl/install_guide).
1. Create an admin account for the Ubuntu Bash environment when prompted.
3. In a local copy of Drupal VM (downloaded or Git cloned into a path that's in the Windows filesystem, e.g. `/mnt/c/Users/yourusername/Sites/drupal-vm`), run `wrun vagrant up`.
If you need to run any other `vagrant` commands (with the exception of `vagrant ssh`—for now, that must be run in a different environment; see [Vagrant: Use Linux Subsystem on Windows](https://github.com/mitchellh/vagrant/issues/7731)), you can do so by prefixing them with `wrun`.
> Note: using `wrun`, interactive prompts don't seem to work (e.g. if you run `vagrant destroy` without `-f`, you have to Ctrl-C out of it because it just hangs).
>
> Note 2: that the WSL is still in beta, and tools like `cbwin` are still undergoing rapid development, so some of these instructions are subject to change!
## Command line environment
If you're not on Windows 10, or if you don't want to install the WSL, you can use PowerShell, Git Bash, Git Shell, or other PowerShell-based environments with Drupal VM and Vagrant; however you might want to consider using a more POSIX-like environment so you can more easily work with Drupal VM:
- [Cmder](http://cmder.net/) includes built-in git and SSH support, so you can do most things that you need without any additional plugins.
- [Cygwin](https://www.cygwin.com/) allows you to install a large variety of linux packages inside its bash environment, though it can be a little more tricky to manage and is less integrated into the Windows environment.
## Troubleshooting Vagrant Synced Folders
Most issues have to do synced folders. These are the most common ones:
_Read the following to [improve the performance of synced folders by using NFS, samba or rsync](../other/performance.md#improving-performance-on-windows)._
### Symbolic Links
Creating symbolic links in a shared folder will fail with a permission or protocol error.
There are two parts to this:
1. VirtualBox does not allow gets VMs to create symlinks in synced folders by default.
2. Windows does not allow the creation of symlinks unless your local policy allows it; see [TechNet article](https://technet.microsoft.com/en-us/library/dn221947%28v=ws.10%29.aspx). Even if local policy allows it, many users experience problems in the creation of symlinks.
Using Ubuntu bash under Windows 10 _can_ make this easier, but there are still issues when creating and managing symlinks between the bash environment and the guest Vagrant operating system.
### Git and File permissions
If you're using a synced folder for your project, you should choose to either work _only_ inside the VM, or _only_ on the host machine. Don't commit changes both inside the VM and on the host unless you know what you're doing and have Git configured properly for Unix vs. Windows line endings. File permissions and line endings can be changed in ways that can break your project if you're not careful!
You should probably disable Git's `fileMode` option inside the VM and on your host machine if you're running Windows and making changes to a Git repository:
git config core.fileMode false
### "Authentication failure" on vagrant up
Some Windows users have reported running into an issue where an authentication failure is reported once the VM is booted (e.g. `drupalvm: Warning: Authentication failure. Retrying...` — see [#170](https://github.com/geerlingguy/drupal-vm/issues/170)). To fix this, do the following:
1. Delete `~/.vagrant.d/insecure_private_key`
2. Run `vagrant ssh-config`
3. Restart the VM with `vagrant reload`
### Windows 7 requires PowerShell upgrade
If you are running Windows 7 and `vagrant up` hangs, you may need to upgrade PowerShell. Windows 7 ships with PowerShell 2.0, but PowerShell 3.0 or higher is required. For Windows 7, you can upgrade to PowerShell 4.0 which is part of the [Windows Management Framework](http://www.microsoft.com/en-us/download/details.aspx?id=40855).
## Hosts file updates
If you install either the `vagrant-hostsupdater` (installed by default unless removed from `vagrant_plugins` in your `config.yml`) or `vagrant-hostmanager` plugin, you might get a permissions error when Vagrant tries changing the hosts file. On a macOS or Linux workstation, you're prompted for a sudo password so the change can be made, but on Windows, you have to do one of the following to make sure hostsupdater works correctly:
1. Run PowerShell or whatever CLI you use with Vagrant as an administrator. Right click on the application and select 'Run as administrator', then proceed with `vagrant` commands as normal.
2. Change the permissions on the hosts file so your account has permission to edit the file (this has security implications, so it's best to use option 1 unless you know what you're doing). To do this, open `%SystemRoot%\system32\drivers\etc` in Windows Explorer, right-click the `hosts` file, and under Security, add your account and give yourself full access to the file.
## Intel VT-x virtualization support
On some laptops, Intel VT-x virtualization (which is built into most modern Intel processors) is enabled by default. This allows VirtualBox to run virtual machines efficiently using the CPU itself instead of software CPU emulation. If you get a message like "VT-x is disabled in the bios for both all cpu modes" or something similar, you may need to enter your computer's BIOS settings and enable this virtualization support.

102
box/docs/getting-started/syncing-folders.md Normal file
View file

@ -0,0 +1,102 @@
You can share folders between your host computer and the VM in a variety of ways; the most commonly-used method is an NFS share. If you use Windows and encounter any problems with NFS, try switching to `smb`. The `default.config.yml` file contains an example `nfs` share that would sync the entire drupal-vm directory (configured as the relative path `.`) on your host into the `/var/www/drupalvm` folder on Virtual Machine.
If you want to use a different synced folder method (e.g. `smb`), you can change `type`:
```yaml
vagrant_synced_folders:
- local_path: .
destination: /var/www/drupalvm
type: smb
create: true
```
You can add as many synced folders as you'd like, and you can configure [any type of share](https://www.vagrantup.com/docs/synced-folders/index.html) supported by Vagrant; just add another item to the list of `vagrant_synced_folders`.
## Options
The synced folder options exposed are `type`, `excluded_paths` (when using rsync), `id`, `create`, `mount_options` and `nfs_udp`. Besides these there are some sane defaults set when using rsync. For example all files synced with rsync will be writable by everyone, thus allowing the web server to create files.
### Overriding defaults
If you feel the need to fine-tune some of the options not exposed, the entire options hash passed to Vagrant can be overriden using `options_override`.
The merge of the default options and `options_override` is shallow, so you can use it to remove flags from eg. `rsync__args`.
One scenario where this might be useful is when you are moving generated code from the virtual machine back to your local machine and you want the files to have appropriate permissions instead of the default 666/777.
```yaml
options_override:
owner: vagrant
group: www-data
rsync__args: [
"--verbose", "--archive", "--delete",
"--chmod=gu=rwX,o=rX", # 664 for files, 775 for directories
]
```
## Synced Folder Troubleshooting
_Read the following [overview on the performance of the different synced folder mechanisms](../other/performance.md#synced-folder-performance)._
There are a number of issues people encounter with synced folders from time to time. The most frequent issues are listed below with possible solutions:
### Using Native Synced Folders
You can use a native synced folder, which should work pretty flawlessly on any platform, but with a potential serious performance downside (compared to other synced folder methods). Just set `type` to `""`.
```yaml
vagrant_synced_folders:
- local_path: .
destination: /var/www/docroot
type: ""
create: true
```
See [this issue](https://github.com/geerlingguy/drupal-vm/issues/67) for more information.
### Permissions-related errors
If you're encountering errors where Drupal or some other software inside the VM is having permissions issues creating or deleting files inside a synced folder, you might need to either make sure the file permissions are correct on your host machine (if a folder is not readable by you, it probably also won't be readable when mounted via NFS!), or add extra configuration to the synced folders item (if using a sync method like `rsync`):
```yaml
vagrant_synced_folders:
- local_path: .
destination: /var/www/drupalvm
type: ""
create: true
mount_options: ["dmode=775", "fmode=664"]
options_override:
owner: "vagrant"
group: "www-data"
```
See [this issue](https://github.com/geerlingguy/drupal-vm/issues/66) for more details.
### Using [`vagrant-bindfs`](https://github.com/gael-ian/vagrant-bindfs) to work around permissions-related errors
If you're using NFS synced folders the mounted directories will use the same numeric permissions on the guest VM as on the host OS. If you're on OSX for instance, your files within the VM would be owned by 501:20. To correct these permissions you can use the [`vagrant-bindfs` plugin](https://github.com/gael-ian/vagrant-bindfs) to mount your NFS folders to a temporary location and then re-mount them to the actual destination with the correct ownership.
First install the plugin with `vagrant plugin install vagrant-bindfs` and then add a `Vagrantfile.local` with the following:
```rb
vconfig['vagrant_synced_folders'].each do |synced_folder|
case synced_folder['type']
when "nfs"
guest_path = synced_folder['destination']
host_path = File.expand_path(synced_folder['local_path'])
config.vm.synced_folders[guest_path][:guestpath] = "/var/nfs#{host_path}"
config.bindfs.bind_folder "/var/nfs#{host_path}", guest_path,
u: 'vagrant',
g: 'www-data',
perms: 'u=rwX:g=rwD',
o: 'nonempty'
config.nfs.map_uid = Process.uid
config.nfs.map_gid = Process.gid
end
end
```
### Other NFS-related errors
If you're having other weird issues, and none of the above fixes helps, you might want to try a different synced folder method (see top of this page), or something like File Conveyor or a special rsync setup (see [here](http://wolfgangziegler.net/auto-rsync-local-changes-to-remote-server#comments) for some examples).