initial documentation

Antonio Terceiro
1 parent 9d54c590
Showing 2 changed files with 77 additions and 0 deletions Show diff stats
.gitignore
README.md
@@ -3,3 +3,4 @@
 /.ssh_config
 /.tmp
 /docs/_build
+/.*.html
@@ -0,0 +1,76 @@
+# Software Público - configuration management
+
+## Requirements
+
+* [chake](https://rubygems.org/gems/chake)
+* rake
+
+For development
+
+* vagrant
+
+## Configuration parameters
+
+For development, all configuration parameters are defined in the file
+`nodes.yaml`.
+
+For production, create a new file based on `nodes.yaml`, e.g.
+`prod.yaml`.
+
+Todos os parâmetros de configuração estão definidos no arquivo nodes.yaml
+
+## Deploy
+
+### Development
+
+First you have to bring up the development virtual machines:
+
+```bash
+$ vagrant up
+```
+
+Right now there are 5 VM's, so this might take a while. The basic commands for
+deployment:
+
+```bash
+$ rake                                  # deploys all servers
+$ rake nodes                            # lists all servers
+$ rake converge:$server                 # deploys only $server
+```
+
+### Production
+
+* TODO: document adding the SSL key and certificate
+* TODO: document creation of `prod.yaml`.
+* TODO: document SSH configuration
+
+```bash
+$ rake NODES=prod.yaml                  # deploys all servers
+$ rake nodes NODES=prod.yaml            # lists all servers
+$ rake converge:$server NODES=prod.yaml # deploys only $server
+```
+
+You can also do `export NODES=prod.yaml` in your shell and omit the
+`NODES=prod.yaml` parameter in the `rake` calls.
+
+See the output of `rake -T` for other tasks.
+
+## Viewing the running site in development
+
+Run:
+
+```bash
+./server
+```
+
+Follow the on-screen instructions an browse to
+[http://softwarepublico.dev/](http://softwarepublico.dev/).
+
+Note: this requires that your system will resolve `\*.dev` to `localhost`.
+Google DNS servers will do that automatically, otherwise you might add the following entries to `/etc/hosts`:
+
+```
+127.0.53.53 softwarepublico.dev
+127.0.53.53 listas.softwarepublico.dev
+```
+
...	...	@@ -3,3 +3,4 @@
3	3	/.ssh_config
4	4	/.tmp
5	5	/docs/_build
	6	+/.*.html
...	...
...	...	@@ -0,0 +1,76 @@
	1	+# Software Público - configuration management
	2	+
	3	+## Requirements
	4	+
	5	+* [chake](https://rubygems.org/gems/chake)
	6	+* rake
	7	+
	8	+For development
	9	+
	10	+* vagrant
	11	+
	12	+## Configuration parameters
	13	+
	14	+For development, all configuration parameters are defined in the file
	15	+`nodes.yaml`.
	16	+
	17	+For production, create a new file based on `nodes.yaml`, e.g.
	18	+`prod.yaml`.
	19	+
	20	+Todos os parâmetros de configuração estão definidos no arquivo nodes.yaml
	21	+
	22	+## Deploy
	23	+
	24	+### Development
	25	+
	26	+First you have to bring up the development virtual machines:
	27	+
	28	+```bash
	29	+$ vagrant up
	30	+```
	31	+
	32	+Right now there are 5 VM's, so this might take a while. The basic commands for
	33	+deployment:
	34	+
	35	+```bash
	36	+$ rake # deploys all servers
	37	+$ rake nodes # lists all servers
	38	+$ rake converge:$server # deploys only $server
	39	+```
	40	+
	41	+### Production
	42	+
	43	+* TODO: document adding the SSL key and certificate
	44	+* TODO: document creation of `prod.yaml`.
	45	+* TODO: document SSH configuration
	46	+
	47	+```bash
	48	+$ rake NODES=prod.yaml # deploys all servers
	49	+$ rake nodes NODES=prod.yaml # lists all servers
	50	+$ rake converge:$server NODES=prod.yaml # deploys only $server
	51	+```
	52	+
	53	+You can also do `export NODES=prod.yaml` in your shell and omit the
	54	+`NODES=prod.yaml` parameter in the `rake` calls.
	55	+
	56	+See the output of `rake -T` for other tasks.
	57	+
	58	+## Viewing the running site in development
	59	+
	60	+Run:
	61	+
	62	+```bash
	63	+./server
	64	+```
	65	+
	66	+Follow the on-screen instructions an browse to
	67	+[http://softwarepublico.dev/](http://softwarepublico.dev/).
	68	+
	69	+Note: this requires that your system will resolve `\*.dev` to `localhost`.
	70	+Google DNS servers will do that automatically, otherwise you might add the following entries to `/etc/hosts`:
	71	+
	72	+```
	73	+127.0.53.53 softwarepublico.dev
	74	+127.0.53.53 listas.softwarepublico.dev
	75	+```
	76	+
...	...