Merge pull request #12900 from annando/robust-html

[friendica.git] / doc / Vagrant.md

diff --git a/doc/Vagrant.md b/doc/Vagrant.md
index fd6b818e7841c5c70cbb51b2b034ccd2be9977e3..ea098e3fb0c7631771a591d341c6f0d8d0206f1c 100644 (file)
--- a/doc/Vagrant.md
+++ b/doc/Vagrant.md
@@ -3,15 +3,34 @@ Vagrant for Friendica Developers
 
 * [Home](help)
 
 
 * [Home](help)
 

-[Vagrant](https://www.vagrantup.com/) is a virtualization solution for developers. No need to setup up a webserver, database etc. before actually starting. Vagrant creates a virtual machine (an Ubuntu 12.04) for you that you can just run inside VirtualBox and start to work directly on Friendica. What you need to do:
+Getting started
+---------------
+
+[Vagrant](https://www.vagrantup.com/) is a virtualization solution for developers.
+No need to setup up a webserver, database etc. before actually starting.
+Vagrant creates a virtual machine for you that you can just run inside VirtualBox and start to work directly on Friendica.
+
+It brings an Debian Bullseye with PHP 8.0 and MariaDB 10.5.11.
+
+What you need to do:

 
 1. Install VirtualBox and vagrant.
 
 1. Install VirtualBox and vagrant.

-2. Git clone your Friendica repository. Inside, you'll find a "Vagrantfile" and some scripts in the utils folder.
-3. Run "vagrant up" from inside the friendica clone. Be patient: When it runs for the first time, it downloads an Ubuntu Server image.
-4. Run "vagrant ssh" to log into the virtual machine to log in to the VM.
-5. Open 192.168.22.10 in a browser to finish the Friendica installation. The mysql database is called "friendica", the mysql user and password both are "root".
+Please use an up-to-date vagrant version from https://www.vagrantup.com/downloads.html.
+2. Git clone your Friendica repository.
+Inside, you'll find a `Vagrantfile` and some scripts in the `bin/dev` folder.
+Pull the PHP requirements with `bin/composer install`.
+3. Run `vagrant up` from inside the friendica clone.
+This will start the virtual machine.
+Be patient: When it runs for the first time, it downloads a Debian Server image and installs Friendica.
+4. Run `vagrant ssh` to log into the virtual machine to log in to the VM in case you need to debug something on the server.
+5. Open you test installation in a browser.
+Go to friendica.local (or 192.168.56.10).
+friendica.local is using a self-signed TLS certificate, so you will need to add an exception to trust the certificate the first time you are visiting the page.
+The mysql database is called "friendica", the mysql user and password both are "friendica".

 6. Work on Friendica's code in your git clone on your machine (not in the VM).
 6. Work on Friendica's code in your git clone on your machine (not in the VM).

-7. Check the changes in your browser in the VM. Debug via the "vagrant ssh" login.
+Your local working directory is set up as a shared directory with the VM (/vagrant).
+7. Check the changes in your browser in the VM.
+Find the Friendica log file `/vagrant/logfile.out` on the VM or in the `logfile.out` in you local Friendica directory.

 8. Commit and push your changes directly back to Github.
 
 If you want to stop vagrant after finishing your work, run the following command
 8. Commit and push your changes directly back to Github.
 
 If you want to stop vagrant after finishing your work, run the following command


@@ -19,5 +38,32 @@ If you want to stop vagrant after finishing your work, run the following command
                $> vagrant halt
 
 in the development directory.
                $> vagrant halt
 
 in the development directory.

+This will not delete the virtual machine.
+9. To ultimately delete the virtual machine run
+
+        $> vagrant destroy
+        $> rm /vagrant/config/local.config.php
+
+to make sure that you can start from scratch with another "vagrant up".
+
+Default User Accounts
+---------------------
+
+By default the provision script will setup two user accounts.
+
+  * admin, password admin
+  * friendica, password friendica
+
+Trouble Shooting
+----------------
+
+If you see a version mis-match for the _VirtualBox Guest Additions_ between host and guest during the initial setup of the Vagrant VM, you will need to install an addon to Vagrant (ref. [Stack Overflow](https://stackoverflow.com/a/38010683)).
+Stop the Vagrant VM and run the following command:
+
+       $> vagrant plugin install vagrant-vbguest 
+
+On the next Vagrant up, the version problem should be fixed.
+
+If `friendica.local` is not resolved, you may need to add an entry to the `/etc/hosts` file (or similar configuration depending on the OS you are using).

 
 For further documentation of vagrant, please see [the vagrant*docs*](https://docs.vagrantup.com/v2/).
 
 For further documentation of vagrant, please see [the vagrant*docs*](https://docs.vagrantup.com/v2/).