Skip to content

Commit ca4ccf2

Browse files
nickjjnickjj
committed
Add getting started with ginas guide
1 parent e424527 commit ca4ccf2

2 files changed

Lines changed: 298 additions & 1 deletion

File tree

‎docs/getting-started-with-ginas.rst‎

Lines changed: 295 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,295 @@
1+
What does this guide cover?
2+
---------------------------
3+
4+
The general theme of this guide will be how to install ansible on your
5+
work station and then use ginas to manage 0 or more linux containers so
6+
you can happily setup and teardown servers that mimic your production
7+
environment!
8+
9+
What operating systems are compatible as work stations?
10+
'''''''''''''''''''''''''''''''''''''''''''''''''''''''
11+
12+
This guide was written and tested against a fresh xubuntu 14.04 work
13+
station however similar ubuntu derivatives should work.
14+
15+
What operating systems are compatible as containers?
16+
''''''''''''''''''''''''''''''''''''''''''''''''''''
17+
18+
By default ginas will use debian wheezy as the base for each container
19+
it creates. For the most part it is compatible with ubuntu 12.04 LTS.
20+
You may have to make a few minor changes in your custom playbooks to
21+
make it work on both debian wheezy and ubuntu 12.04 LTS.
22+
23+
What is the ansible skill level expectation for this guide?
24+
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
25+
26+
You are expected to be pretty familiar with ansible but you definitely
27+
do not need to be an expert. You should know what an inventory or
28+
playbook is, etc..
29+
30+
Table of contents
31+
-----------------
32+
33+
- `Install ansible on your work station <#install-ansible>`__
34+
- `Configure your inventory <#configure-inventory>`__
35+
- `Run the common playbook <#common-playbook>`__
36+
- `Setup your first linux container <#first-container>`__
37+
- `Access your container in a browser from your work station <#browse-container>`__
38+
39+
Install ansible on your work station
40+
------------------------------------
41+
42+
For the sake of this guide we are going to make a few assumptions about
43+
where things will be installed and what the hostname of the work station
44+
is. Feel free to customize these values because they are not important
45+
to getting ansible and ginas setup correctly.
46+
47+
The work station will be named ``beast`` and your "I put my source code
48+
here" path will be ``~/src``.
49+
50+
::
51+
52+
# -----------------------------------------------------------------------------
53+
# Install the bare necessities.
54+
# -----------------------------------------------------------------------------
55+
# TIP: Feel free to remove vim and mc (midnight commander) if you don't want em.
56+
sudo apt-get install git lsb-release vim mc make
57+
58+
# -----------------------------------------------------------------------------
59+
# Clone ginas into a directory of your choice.
60+
# -----------------------------------------------------------------------------
61+
# TIP: For the sake of this guide we are cloning to ~/src/ansible.
62+
git clone https://github.com/ginas/ginas.git ~/src/ansible/ginas
63+
64+
# -----------------------------------------------------------------------------
65+
# Setup the inventory file and directories.
66+
# -----------------------------------------------------------------------------
67+
cd ~/src/ansible/ginas
68+
mkdir -p hosts inventory/group_vars inventory_host_vars
69+
70+
# -----------------------------------------------------------------------------
71+
# Run the bootstrap command to install ansible.
72+
# -----------------------------------------------------------------------------
73+
# TIP: It will install the development branch which is reasonably stable.
74+
./contrib/bootstrap-ansible.sh
75+
76+
At this point you should have ansible installed on your work station.
77+
You can verify this by entering ``ansible --version`` in your terminal.
78+
You should get back a version number.
79+
80+
Configure your inventory
81+
------------------------
82+
83+
Now for the good stuff, we're going to run the common tasks for ginas.
84+
First off we will configure some basic settings though.
85+
86+
::
87+
88+
# -----------------------------------------------------------------------------
89+
# Add any custom packages you want installed.
90+
# -----------------------------------------------------------------------------
91+
vi inventory/host_vars/beast.yml
92+
93+
# Your file could look like this (without the comments):
94+
---
95+
# Install libpq-dev because I am a rails developer and I want to be able to connect
96+
# to a postgres database. You do not need this unless you have the same needs as me.
97+
apt_host_packages: ['libpq-dev']
98+
99+
# Notice how it's added to the apt_host_packages list. This will only be applied to
100+
# your work station which is named beast.
101+
102+
# -----------------------------------------------------------------------------
103+
# Setup basic configuration to be applied to all hosts.
104+
# -----------------------------------------------------------------------------
105+
vi inventory/group_vars/all.yml
106+
107+
# Your file should look like this (without the comments):
108+
---
109+
# Remove this line if you do not want dotfiles installed.
110+
users_dotfiles_enabled_default: True
111+
112+
# Remove this line if you want bash instead.
113+
users_default_shell: '/bin/zsh'
114+
115+
# The admin account of the server will be set as ansible_ssh_user.
116+
# If you run your playbook without setting -u <some user> then
117+
# ansible will use your work station's user as the default.
118+
auth_admin_accounts: [ '{{ ansible_ssh_user }}' ]
119+
120+
# Some configuration to ensure packages are pulled from the correct mirror.
121+
# TIP: If you are not from the US you might want to change the mirror url.
122+
apt_debian_http_mirror: 'ftp.us.debian.org'
123+
lxc_template_debootstrap_mirror: 'http://{{ apt_debian_http_mirror }}/debian'
124+
125+
# Set the default locale.
126+
# TIP: If you are not from the US you might want to use a different locale.
127+
console_locales: ['en_US.UTF-8']
128+
129+
# -----------------------------------------------------------------------------
130+
# Setup the hosts file
131+
# -----------------------------------------------------------------------------
132+
vi hosts
133+
134+
# Your file should look like this (without the comments):
135+
---
136+
# This tells ansible that you want commands to be ran locally for localhost.
137+
localhost ansible_connection=local
138+
139+
# We are grouping our work station to limit tasks later for only our WS.
140+
[ansible_workstation]
141+
beast ansible_connection=local
142+
143+
If all goes as planned you should be able to check out some ansible
144+
facts about your host by entering ``./task.sh beast -m setup | less``.
145+
If that command worked you should see the facts and that verifies
146+
ansible has been setup correctly and is capable of talking to your work
147+
station.
148+
149+
Run the common playbook
150+
-----------------------
151+
152+
Now that everything is configured we can run the common playbook. This
153+
is going to setup your work station with proper DNS, postfix support and
154+
many other useful services. This section is short and sweet. Just enter
155+
``./site.sh -K`` and provide your sudo password. In the future we won't
156+
have to provide -K because one of the things that the common playbook
157+
does is setup ssh keys and enable passwordless sudo.
158+
159+
If that worked properly then you must log out of your work station and
160+
log back in. Certain permissions were changed for your user so that step
161+
is required, you cannot just open a new terminal or source your shell
162+
config.
163+
164+
After logging back in you should verify that you can access root without
165+
a password. Enter ``sudo su`` and you should be greeted with a root
166+
prompt. Just hit ``CTRL+D`` or type ``logout`` to get back to your
167+
normal user.
168+
169+
Setup your first linux container
170+
--------------------------------
171+
172+
This is where things get interesting. In a few minutes you'll be able to
173+
setup as many linux containers as you want in seconds.
174+
175+
::
176+
177+
# -----------------------------------------------------------------------------
178+
# Make sure your ssh keys are setup
179+
# -----------------------------------------------------------------------------
180+
# TIP: Skip this step and copy over any existing keys to ~/.ssh if you have em.
181+
ssh-keygein -t rsa
182+
183+
# -----------------------------------------------------------------------------
184+
# Fix a potential bug with ubuntu and linux containers
185+
# -----------------------------------------------------------------------------
186+
# You will likely get errors without installing this package first.
187+
sudo apt-get install libcgmanager0
188+
189+
# -----------------------------------------------------------------------------
190+
# Create the container in your inventory
191+
# -----------------------------------------------------------------------------
192+
# TIP: Add the following to this file.
193+
vi inventory/host_vars/beast.yml
194+
195+
# A list of containers to add.
196+
lxc_containers:
197+
# What should the container be named?
198+
- name: 'first'
199+
# Should it be started automatically?
200+
# TIP: You can set this to 'absent' to delete the container.
201+
state: 'started'
202+
# Setup nat.
203+
network: 'nat'
204+
config: True
205+
206+
# -----------------------------------------------------------------------------
207+
# Add the container to your hosts
208+
# -----------------------------------------------------------------------------
209+
# TIP: Add the following to this file.
210+
vi inventory/hosts
211+
212+
# We want to let ginas know that our work station will be storing the containers.
213+
[ginas_lxc]
214+
beast
215+
216+
# -----------------------------------------------------------------------------
217+
# Create the container
218+
# -----------------------------------------------------------------------------
219+
# Run the lxc role on the work station.
220+
./site.sh --limit ginas_lxc
221+
222+
# You can expect this command to take a while on the first run. The first
223+
# container has to download a bunch of packages from apt but once it finishes
224+
# the first run it caches those packages.
225+
226+
# Future containers will take only a few seconds to create even if you delete
227+
# this one. Yep, linux containers are amazing.
228+
229+
You should now have a container available to be managed by whatever you
230+
want. You can verify that it works by typing:
231+
232+
``ping first`` and ``ssh first``. Since we have DNS setup properly we
233+
can access them easily.
234+
235+
To add more containers just open ``inventory/host_vars/beast.yml`` and
236+
add it to the list of containers. Then run ``./site.sh --tags lxc`` and
237+
it will be added.
238+
239+
You can also see which containers are running by entering
240+
``sudo lxc-ls -f``. Another tip to delete containers faster is to enter
241+
``sudo lxc-destroy -f -n <container_name>`` rather than changing the
242+
inventory to set it as absent.
243+
244+
Access your container in a browser from your work station
245+
---------------------------------------------------------
246+
247+
All of the commands below are to be ran on your work station.
248+
249+
::
250+
251+
# -----------------------------------------------------------------------------
252+
# Let /etc/hosts know about your work station domain
253+
# -----------------------------------------------------------------------------
254+
sudo vi /etc/hosts
255+
256+
# Edit your file to include this line by ovewriting the old 127.0.1.1 line.
257+
# TIP: You can choose something other than .dev, but you need at least 1 dot.
258+
127.0.1.1 beast.dev beast
259+
260+
# -----------------------------------------------------------------------------
261+
# Enable wildcard sub-domain support
262+
# -----------------------------------------------------------------------------
263+
vi inventory/host_vars/beast.yml
264+
265+
# You must add each container to this list.
266+
dnsmasq_address:
267+
# first... this is the container name.
268+
# nat... we are on the network.
269+
# beast... your work station hostname.
270+
# dev... the extension
271+
# IP... this is the IP address of the container
272+
'.first.nat.beast.dev': '192.168.144.1'
273+
274+
# TIP: To find the IP address of the container run this:
275+
# cat /etc/network/interfaces.d/40_nat_br2
276+
# It will be marked next to the 'address' field.
277+
278+
# -----------------------------------------------------------------------------
279+
# Update your containers to reflect the DNS changes
280+
# -----------------------------------------------------------------------------
281+
./site --limit ginas_lxc
282+
283+
You can verify that wildcard sub-domains work by entering
284+
``ping foo.first``, you should get a reply.
285+
286+
That's it. You can now open a browser on your work station and visit
287+
``http://first.nat.beast.dev/``. You will get an unable to connect
288+
message because there are no web servers running. You can verify this by
289+
trying to goto ``http://foo.nat.beast.dev``, you will see a no server
290+
errror instead.
291+
292+
Have fun
293+
''''''''
294+
295+
Don't forget to use ansible to provision your containers!

‎docs/index.rst‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,9 @@ Contents:
1818
.. toctree::
1919
:maxdepth: 2
2020

21-
21+
Guides
22+
======
23+
* :ref:`getting-started-with-ginas`
2224

2325
Indices and tables
2426
==================

0 commit comments

Comments
 (0)