Commit 3683d71 Add documentation for vagrant use.

3 files Authored and Committed by davidcarlos 4 months ago
Add documentation for vagrant use.

  - Add taks to run migrations.

    
 1 @@ -2,13 +2,16 @@
 2   ====================
 3   
 4   This section is a guide for new developers willing to set up a development
 5 - environemnt to start contributing to kiskadee development. If you have any
 6 + environment to start contributing to kiskadee. If you have any
 7   doubt, please contact us on IRC in #kiskadee at freenode or join the
 8   development discussion in our mailing list at kiskadee@googlegroups.com.
 9   
10 - **kiskadee development only suports python versions >= 3. Assume such versions
11 + **kiskadee development only supports python versions >= 3. Assume such versions
12   for all commands run along this documentation.**
13   
14 + **This documentation covers step by step how install kiskadee. If you want to
15 + quickly configure an development environment, check the installing documentation.**
16 + 
17   Installing dependencies
18   -----------------------
19   
20 @@ -16,7 +19,7 @@
21   you use another OS, you will have to find the compatible names
22   for the dependencies.
23   
24 - `dnf` is Fedora package manager. One should make proper subtitutions when using
25 + `dnf` is Fedora package manager. One should make proper substitutions when using
26   another linux distribution.
27   
28   The `redhat-rpm-config` package, is a specific Fedora dependency, if you do not
29 @@ -177,7 +180,7 @@
30   
31     $ alembic revision -m "migration description"
32   
33 - **To autogenerate a new migration**
34 + **To auto generate a new migration**
35   
36   .. code-block:: bash
37   
38 @@ -209,7 +212,7 @@
39   
40   Kiskadee database migration tool(alembic) get its database configuration
41   from a environment variable named DATABASE_TYPE.
42 - If this variable is not defined, then it will assume its running on a developemnt
43 + If this variable is not defined, then it will assume its running on a development
44   environment, but for others environments such as test, homologation or
45   production be sure to set which one are being used.
46   
 1 @@ -3,17 +3,65 @@
 2   
 3   Development
 4   -----------
 5 - First, make shure that ansible will be able to login on the vm. ansible will
 6 - use the root user to do this, so you will have to add your public ssh
 7 + To quick setup kiskadee environment you can use our ansible playbook with
 8 + vagrant. The first thing to do is to create the virtual machines necessary to
 9 + run kiskadee. Kiskadee backend runs on the kiskadee-core vm, so lets create
10 + it:
11 + 
12 + .. code-block:: bash
13 + 
14 +     vagrant up
15 + 
16 + This command will create all vagrant images. You can take a look on
17 + Vagrantfile, to check which virtual machines are available. kiskadee uses libvirt
18 + + qemu to manage virtual machines. If you are using virtualbox as hypervisor, 
19 + you will need to hack the Vagrantfile and adapt it to your needs (send us a PR :) ).
20 + 
21 + .. warning::
22 + 
23 +         If you are using libvirt to manage vms, and you see a error saying that
24 +         a domain for kiskadee-core already exists, you can remove (with root) the old domain:
25 + 
26 +         .. code-block:: bash
27 + 
28 +            virsh undefine kiskadee_kiskadee-core
29 + 
30 +         Drop the old vm:
31 + 
32 +         .. code-block:: bash
33 + 
34 +            vagrant destroy kiskadee-core
35 + 
36 +         And run `vagrant up` again.
37 + 
38 + 
39 + First, make sure that ansible will be able to login on the vm. ansible will
40 + use the root user to do that, so you will have to add your public ssh
41   key inside the root **~/.ssh/authorized_keys** file. You can also create the host
42   user inside the vm, in order to be able to test the vm access with the ping
43 - command.
44 + command. To add your ssh key run:
45 + 
46 + .. code-block:: bash
47 + 
48 +     vagrant ssh kiskadee-core
49 +     sudo su
50 +     ssh-keygen
51 + 
52 + Append your public key inside the **~/.ssh/authorized_keys** file and **logout** the vm.
53 + 
54 + Install the ansible package:
55   
56 - To check if ansible can access the machine:
57 + .. code-block:: bash
58 + 
59 +    sudo pip install ansible
60 + 
61 + To check if ansible can access the kiskadee-core virtual machine:
62   
63   .. code-block:: bash
64   
65 -     ansible -i playbook/hosts.local all  -m ping
66 +     ansible -i playbook/hosts.local kiskadee-core  -m ping
67 + 
68 + If you see a success message, we are good to go.
69   
70   To deploy kiskadee locally:
71   
72 @@ -21,6 +69,14 @@
73   
74       ansible-playbook  -c paramiko -i playbook/hosts.local playbook/local.yml
75   
76 + To test if kiskadee was installed correctly, log in the kiskadee-core vm and
77 + inside the kiskadee folder call the command `kiskadee`. If the environment is
78 + properly configured, kiskadee will run a simple analysis using the example
79 + fetcher.
80 + 
81 + You can start kiskadee api running `kiskadeee_api`. 
82 + You can access the list of analyzed packages on `localhost:5000/packages`.
83 + 
84   Production
85   ----------
86   
 1 @@ -1,3 +1,7 @@
 2 + - name: Turn off selinux
 3 +   command: setenforce 0
 4 +   ignore_errors: yes
 5 + 
 6   - name: Install kiskadee
 7     command: pip3 install -e .
 8     args:
 9 @@ -20,6 +24,7 @@
10       chdir: /home/vagrant/kiskadee
11       target: analyzers
12   
13 - - name: Turn off selinux
14 -   command: setenforce 0
15 -   ignore_errors: yes
16 + - name: migrate database
17 +   command: alembic upgrade head
18 +   args:
19 +     chdir: /home/vagrant/kiskadee