Start to test all json schema and files.
[slapos.git] / software / slaprunner / README.txt
1 slaprunner
2 ==========
3
4 Introduction
5 ------------
6
7 This software release is used to deploy Slaprunner instances.
8 Slaprunner is an all-in-one IDE used to develop and test profiles and recipes for SlapOS.
9
10 You can learn how to use it here :
11 http://community.slapos.org/wiki/slapos-Wiki.Home/developer-Lecture.Web.Runner.Extended
12
13 Parameters
14 ----------
15
16 user-authorized-key
17 ~~~~~~~~~~~~~~
18
19 You need to specify your SSH public key in order to connect to the SSH server of this instance.
20
21 Example of parameter XML::
22
23   <?xml version="1.0" encoding="utf-8"?>
24   <instance>
25   <parameter id="user-authorized-key">ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCdNp7qZMVAzNc07opHshiIFDmJpYXQpetfcSgUj39a409d42PpsJElp7WsAE/x0nN6gUIoWIl7UiAlMzf6bKEJGJVSOZEPTmiJVlgK1Gp+kE0x9yNcncYg7p38Jny0daVA/NkkpAFyRsAm5kLGzyLtaCcktSvy0cJuy7WSSHU05pd1f8Y8thofE9g5t+/JA2VZvipxPkRfkFAG3aOAGLULlTImTSDFSDFGSDFG5F6mMnl7yvY2d6vEHVBu+K+aKmAwZVfCUwtSpa/tq3i2Lppjrw3UfrxbQSFHZCkzefr+u+l4YYe+tJrX7rYJYXD7LIfZfdSeFTlHFaN/yI1 user@host.local</parameter>
26   </instance>
27
28 instance-amount
29 ~~~~~~~~~~~~~~~
30
31 Optional parameter.
32
33 Default: 10
34
35
36 Public-directory
37 ----------------
38 You can serve static files with the webrunner. For that, just put your data in "srv/runner/public". All these files will be served throught the url of the webrunner + "/public/". Useful for developping your own static website.
39
40
41 AUTO-DEPLOYMENT
42 ---------------
43
44 for software
45 ~~~~~~~~~~~~
46
47 You can automatically deploy a software release while deploying the webrunner itself, using the paramater XML.
48
49 To do this, you only need to pass as a parameter named "slapos-software" : "AAA/BBB", where AAA is the folder of slapos.git where is located your BBB software.
50 For example, to deploy the hello-world software, you need to pass : software/helloworld
51
52 This is possible because the slapos.git is automatically downloaded when the webrunner is deployed.
53
54 It is also possible to download you own git repository, by providing the url in the "slapos-repository" parameter.
55
56 Last but not least, it is also possible to switch the branch with the parameter "slapos-reference" (by default pointing on master)
57
58 for instance
59 ~~~~~~~~~~~~
60
61 The parameter "auto-deploy-instance" can be explicitly set to allow or prevent the runner to deploy the instance at START TIME (if you manually restart the runner, or if the server reboots). Values : "true" or "false". Default value is "true", except for the instances of import (while type is resilient or test) which is "false"
62
63 There also exists the parameter "autorun", which will build&run your software if set to true. For this, you need "auto_deploy" to true, and set the parameter "slapos-software" to the software you want to deploy. Do not hesitate to clone a different repo than "slapos", or to change the tag/branch to use your custom Software Release. (see "slapos-repository" and "slapos-reference" in previous section).
64
65 To deploy the instance with some parameters, just give to the runner parameters starting with "parameter-", they will be correctly forwarded to the instance, which will use them for its configuration. For example, if you want to send to the sofware helloworld the parameter "name" with the value "nicolas", here is how to configure the parameter.xml of the webrunner for auto-depolyment :
66
67 <?xml version='1.0' encoding='utf-8'?>
68 <instance>
69 <parameter id="slapos-software">software/helloworld</parameter>
70 <parameter id="auto_deploy">true</parameter>
71 <parameter id="autorun">true</parameter>
72 <parameter id="parameter-name">nicolas</parameter>
73 </instance>
74
75 Resilience :
76 ------------
77
78 To order a resilient runner, you have to request a runner with the option: "--type resilient"
79
80 You can then decide on which node you want to deploy each instance, with the parameters.xml :
81         <?xml version='1.0' encoding='utf-8'?>
82         <instance>
83           <parameter id="-sla-runner2-computer_guid">COMP-XXXX</parameter>
84           <parameter id="-sla-pbs2-computer_guid">COMP-XXXX</parameter>
85           <parameter id="-sla-pbs1-computer_guid">COMP-XXXX</parameter>
86           <parameter id="-sla-runner1-computer_guid">COMP-XXXX</parameter>
87           <parameter id="-sla-runner0-computer_guid">COMP-XXXX</parameter>
88         </instance>
89
90 If you want to check by yourself that the pull-backup instances do their job, you can change directory to the slappart of runner0, and run ./bin/exporter (after creating your account, using the given backend_url or url): it would fill ./srv/backup/runner with data. If you then go to an import instance (runner1 or runner2) on the port 50005, you should be able to sign in the runner.
91
92
93 Tips :
94 ~~~~~
95
96 To find in which partition the instance has been deployed, you can open the page of this specific instance, and look for "slappartXX" on the page.
97
98 Tests :
99 -------
100
101 To test the runner, start by ordering a runner with default type. Then READ the important note below :
102
103 /!\ IMPORTANT NOTE ON THE TESTS /!\ : in order to make them work, you have to comment the last line of the file __init__.py in the runner module (which is just : "run()"). Indeed, this line is used to load the config, when importing this module throught Gunicorn (the wsgi server). But the test suite loads itself the configuration, in fonction of the tested scenarios, etc... (You can find the module in the SR folder directory, under ./eggs/slapos.toolbox, or under parts/slapos.toolbox if you have a development version)
104
105 Then, su in the concerned slapuserX and run "./bin/runTestSuite".
106
107 For the tests on the resiliency of the webrunner, please refer to the README in slapos.toolbox.git/slapos/resiliencytest
108
109 Request custom frontend :
110 -------------------------
111
112 While deploying a server in your instance, you may need to ask for a custom ipv4 frontend.
113
114 The way to do that is to send a new parameter to your runner instance, using the parameters XML. The name of it is "custom-frontend-backend-url".
115
116 To create the frontend, you now have to wait the slaprunner to be processed.
117
118 You can define the type of your backend using "custom-frontend-backend-type". eg: zope
119
120 If you deploy a server, which uses basic auth, you also have to declare the parameter "custom-frontend-basic-auth" as true, or your slaprunner instance won't show as correctly instanciated.
121
122 Example :
123         <?xml version='1.0' encoding='utf-8'?>
124         <instance>
125         <parameter id="custom-frontend-backend-url">http(s)://[THE_IPV6_ADDRESS]:PORT</parameter>
126         <parameter id="custom-frontend-backend-type">zope</parameter>
127         <parameter id="custom-frontend-basic-auth">true</parameter>
128         </instance>
129
130 Git repositories :
131 ------------------
132
133 It is easy to give access to your git repository/ies to everyone, or to clone it on your own computer. For this, fetch the git_url parameter returned by your webrunner instance. It should look like that : https://[IPV6]:PORT/git/YourRepo.git/
134
135 To create the repo, go to the folder srv/runner/project and initiate a new git repo (git init/clone --bare YourRepo). Then, to clone the repo, just append its name to the previous URL.
136
137 Please notice that your repositories are in public access for reading. However, an account is needed to push to the repository (use your webrunner account, or create a new user in the parameters section of the webrunner).
138
139 For the moment, the PORT is the port of monitoring, which is 9685.
140
141 Things to notice for the nex developer :
142 ----------------------------------------
143
144 As you can see in instance-runner-*.cfg, the buildout section extends a hard-coded template file. If one day you need to modify the filename, do not forget to modify it in instance.cfg, but also in these files ! (the problem is that the content of instance.cfg is not known by buildout while the deployment of the software release)
145
146
147 List of ports used by the webrunner:
148 ------------------------------------
149 8602 : slapproxy, while running tests
150 8949 : shellinabox
151 9684 : apache (monitoring of slaprunner, git access)
152 22222 : dropbear
153 39986 : supervisord
154 50000 : slapproxy
155 50005 : webrunner (flask app), webdav access
156
157 Tips:
158 -----
159 You can use shellinabox in fullscreen, by accessing : https://[IPV6]:8949