rename main yaml and add description

README.md

@@ -2,3 +2,131 @@ ansible-lssd
 ============
 
 Large scale server deploys using BitTorrent and the BitTornado library by [Murder](https://github.com/lg/murder)
+
+DESCRIPTION
+-----------
+ansible-lssd  is a method of using Bittorrent (Powered by [Murder](https://github.com/lg/murder)) to distribute files to a large amount
+of servers within a production environment. 
+
+
+QUICK START
+-----------
+
+For the impatient, `sudo pip install ansible` and add these lines to your group_vars/all:
+
+```bash:
+# install pip (Python package manager) and ansible
+$ sudo easy_install pip
+$ sudo pip install ansible
+```
+
+```YAML:group_vars/all
+# deploy tag
+tag: Deploy1
+
+# path
+seeder_files_path:  ~/builds
+destination_path:   /opt/hoge
+```
+
+
+HOW IT WORKS
+------------
+
+Same as the "[HOW IT WORKS](https://github.com/lg/murder/blob/master/README.md#how-it-works)" of Murder.
+
+
+CONFIGURATION AND USAGE
+-----------------------
+
+You define `tracker`, `seeder` and `peer` server to inventory (./production) file.
+
+All involved servers must have python and pizg installed and the related murder
+support files (BitTornado, etc.). To upload the support files to the
+tracker, seeder, and peers, run:
+
+```bash:
+$ ansible-playbook -i prodction setup.yml
+```
+
+By default, these will go in `/usr/local/murder` in your apps deploy directory. 
+Override this by setting the variable `remote_murder_path`. 
+
+Before deploying, you must start the tracker:
+
+```bash:
+$ ansible-playbook -i prodction start_tracker.yml
+```
+
+At this point you should be able to deploy normally:
+
+```bash:
+$ ansible-playbook -i prodction deploy.yml
+```
+
+
+MANUAL USAGE (ansible-lssd without a deploy strategy)
+-----------------------------------------------------
+
+Modify a ./production and ./group_vars/all, manually define servers:
+
+```INI:production
+# ansible host
+[ansible_host]
+localhost ansible_connection=local
+
+# tracker node
+[tracker]
+10.0.0.1
+
+# seeder node
+[seeder]
+10.0.0.1
+
+# peer nodes
+[peer]
+10.1.1.1
+10.1.1.2
+10.1.1.3
+```
+
+```YAML:group_vars/all
+# deploy tag
+tag: Deploy1
+
+# path
+seeder_files_path:  ~/builds
+destination_path:   /opt/hoge  # or some other directory
+```
+
+To distribute a directory of files, first make sure that murder is set
+up on all hosts, then manually run the murder cap tasks:
+
+1. Start the tracker:
+
+```bash:
+$ ansible-playbook -i prodction start_tracker.yml
+```
+
+2. Create a torrent from a directory of files on the seeder, and start seeding:
+
+```bash:
+$ scp -r ./builds host1:~/builds
+$ ansible-playbook -i prodction create_torrent.yml
+$ ansible-playbook -i prodction start_seeder.yml
+```
+
+3. Distribute the torrent to all peers:
+
+```bash:
+$ ansible-playbook -i prodction deploy.yml
+```
+4. Stop the seeder and tracker:
+
+```bash:
+$ ansible-playbook -i prodction stop_seeder_and_tracker.yml
+```
+
+When this finishes, all peers will have the files in /opt/hoge/Deploy1
+
+

create_torrent.yml

@@ -8,9 +8,3 @@
   roles:
     - murder/create_torrent
 
-- name: Start seeding
-  hosts: seeder
-  sudo: yes
-  roles:
-    - murder/start_seeding
-

deploy.yml

@@ -1,11 +1,9 @@
 
 
 - name: Deploy 
-  hosts: 
+  hosts: peer
-  - peer
-  #- seeder
   sudo: yes
-  #serial: 100
+  serial: 1000
   roles:
     - murder/peer
 

production

@@ -18,5 +18,5 @@ localhost ansible_connection=local
 10.1.1.3
 10.1.1.4
 10.1.1.[5:19] 
-10.2.1.[100:109] ansible_connection=ssh ansible_ssh_private_key_file=private.pem ansible_ssh_user=root
+10.1.1.[100:109] ansible_connection=ssh ansible_ssh_private_key_file=private.pem ansible_ssh_user=root
 

roles/admin/distribute_files/tasks/main.yml

@@ -1,4 +1,6 @@
-
+# SCPs a compressed version of all files from ./dist (the python Bittorrent library and custom scripts) to all server.
+# The entire directory is sent, regardless of the role of each individual server.
+# The path on the server is specified by remote_murder_path and will be cleared prior to transferring files over.
 - name: mkdir destination_path
   file: path={{ destination_path }} state=directory owner=root group=root mode=0755
   tags: distribute_files

roles/admin/start_tracker/tasks/main.yml

@@ -1,4 +1,4 @@
-
+# Starts the Bittorrent tracker (essentially a mini-web-server) listening on port 8998.
 - name: start tracker
   shell: SCREENRC=/dev/null SYSSCREENRC=/dev/null screen -dmS murder_tracker python {{ remote_murder_path }}/murder_tracker.py && sleep 0.2
   tags: start_tracker

roles/admin/stop_all_peering/tasks/main.yml

@@ -1,4 +1,5 @@
-
+# Sometimes peers can go on forever (usually because of an error).
+# This command will forcibly kill all "murder_client.py peer" commands that are running.
 - name: stop all peering
   shell: pkill -f "murder_client.py peer"
   register: result

roles/admin/stop_all_seeding/tasks/main.yml

@@ -1,4 +1,4 @@
-
+# Identical to stop_seeding, except this will kill all seeding processes. No 'tag' argument is needed."
 - name: stop all seeding
   shell: pkill -f "SCREEN.*seeder-"
   register: result

roles/admin/stop_tracker/tasks/main.yml

@@ -1,4 +1,4 @@
-
+# If the Bittorrent tracker is running, this will kill the process. Note that if it is not running you will receive an error.
 - name: stop tracker
   shell: pkill -f 'SCREEN.*murder_tracker.py'
   register: result

roles/murder/peer/tasks/main.yml

@@ -1,4 +1,12 @@
-
+#  Instructs all the peer servers to connect to the tracker and start download and spreading pieces and files amongst themselves.
+# You must specify a valid 'tag' argument.
+# Once the download is complete on a server, that server will fork the download process and seed for 30 seconds while returning control to Ansible.
+# extract the files to the passed in 'destination_path' argument to destination_path/TAG/*.
+# To not create this tag named directory, pass in the 'no_tag_directory=1' argument.
+# If the directory is not empty, this command will fail.
+# To clean it, pass in the 'unsafe_please_delete=1' argument.
+# The compressed tgz in /{{ default_temp_path }} is never removed.
+# When this task completes, all files have been transferred and moved into the requested directory.
 - name: set destination_path
   set_fact: destination_path={{ destination_path }}/{{ tag }}
   when: not no_tag_directory
@@ -9,7 +17,7 @@
   tags: peer
 
 - name: delete destination_path/*
-  shell: rm -rf '{{ destination_path }}a/*'
+  shell: rm -rf '{{ destination_path }}/*'
   when: unsafe_please_delete
   tags: peer
 

roles/murder/start_seeding/tasks/main.yml

@@ -1,4 +1,8 @@
 
+# Will cause the seeder machine to connect to the tracker and start seeding. 
+# The ip address returned by the 'host' bash command will be announced to the tracker. 
+# The server will not stop seeding until the stop_seeding task is called. 
+# You must specify a valid 'tag' argument (which identifies the .torrent in /tmp to use)
 - name: start seeding
   shell: SCREENRC=/dev/null SYSSCREENRC=/dev/null screen -dmS 'seeder-{{ tag }}' python {{ remote_murder_path }}/murder_client.py seeder '{{ filename }}.torrent' '{{ filename }}' {{ ansible_default_ipv4['address'] }}
   tags: start_seeding

roles/murder/stop_seeding/tasks/main.yml

@@ -1,4 +1,7 @@
 
+# If the seeder is currently seeding, this will kill the process.
+# If a peer was downloading from this seed, the peer will find another host to receive any remaining data. 
+# You must specify a valid 'tag' argument.
 - name: stop seeding
   shell: pkill -f "SCREEN.*seeder-{{ tag }}"
   register: result

site.yml

@@ -1,10 +1,11 @@
 ---
 - include: setup.yml
 - include: stop_seeder_and_tracker.yml
-- include: stop_all.yml
+- include: stop_all_peers.yml
 - include: rm_tgz.yml
 - include: start_tracker.yml
 - include: create_torrent.yml
+- include: start_seeder.yml
 - include: deploy.yml
 - include: stop_seeder_and_tracker.yml
 

stop_seeder_and_tracker.yml

@@ -1,13 +1,12 @@
 
-- name: Stop seeding
+- name: Stop seeder
   hosts: seeder
   sudo: yes
   roles:
-    - murder/stop_seeding
+    - admin/stop_seeder
 
 - name: Stop tracker
   hosts: tracker
   sudo: yes
   roles:
     - admin/stop_tracker
-

stop_tracker.yml

@@ -1,13 +0,0 @@
-
-- name: Stop seeding
-  hosts: seeder
-  sudo: yes
-  roles:
-    - murder/stop_seeding
-
-- name: Stop tracker
-  hosts: tracker
-  sudo: yes
-  roles:
-    - admin/stop_tracker
-