Docs: Update docs to prepare for 0.10.0 release
[leap_platform.git] / README.md
1 Leap Platform
2 =============================
3
4 [![Build Status](https://0xacab.org/leap/platform/badges/master/build.svg)](https://0xacab.org/leap/platform/commits/master)
5
6 The LEAP Platform is set of complementary packages and server recipes to
7 automate the maintenance of LEAP services in a hardened Debian environment. Its
8 goal is to make it as painless as possible for sysadmins to deploy and maintain
9 a service provider's infrastructure for secure communication. These recipes
10 define an abstract service provider. It is a set of Puppet modules designed to
11 work together to provide to sysadmins everything they need to manage a service
12 provider infrastructure that provides secure communication services.
13
14 Getting started
15 =============================
16
17 It is highly recommended that you start by reading the overview of the [LEAP
18 Platform](https://leap.se/docs/platform) and then begin with the [Quick Start
19 tutorial](https://leap.se/en/docs/platform/tutorials/quick-start) to walk
20 through a test environment setup to get familiar with how things work before
21 deploying to live servers.
22
23 An offline copy of this documentation is contained in the `docs` subdirectory:
24
25     cd leap_platform
26     gnome-open docs/index.html
27
28 Requirements
29 -----------------------------
30
31 For testing a virtual deployment simulated on your computer, you will need a
32 fairly recent computer x86_64 with hardware virtualization features (AMD-V or
33 VT-x) and plenty of RAM. If you follow the "Quick Start" documentation we will
34 walk you through using Vagrant to setup a test deployment.
35
36 For a live deployment of the platform, the number of servers that is required
37 depends on your needs and which services you want to deploy. At the moment, the
38 LEAP Platform supports servers with a base Debian Jessie installation.
39
40 Upgrading
41 =============================
42
43 If you are upgrading from a previous version of the LEAP Platform, take special
44 care to follow the instructions detailed in the CHANGES.md to move from one
45 release to the next.
46
47 Troubleshooting
48 =============================
49
50 If you have a problem, we are interested in fixing it!
51
52 If you have a problem, be sure to have a look at the [Known
53 Issues](https://leap.se/docs/platform/known-issues) to see if your issue is
54 detailed there.
55
56 If not, the best way for us to solve your problem is if you provide to us the
57 complete log of what you did, and the output that was produced. Please don't
58 cut out what appears to be useless information and only include the error that
59 you received, instead copy and paste the complete log so that we can better
60 determine the overall situation. If you can run the same command that produced
61 the error with a raised verbosity level (such as -v2), that provides us with
62 more useful debugging information.
63
64 To capture the log, you can copy from the console, or run `leap --log FILE` or
65 edit Leapfile to include `@log = '/tmp/leap.log'`.
66
67 Visit https://leap.se/en/docs/get-involved/communication for details on how to
68 contact the developers.
69
70 Known issues
71 ==============================
72
73 ssh
74 ------------------------------
75
76 * At the moment, it is only possible to add an admin who will have access to
77   all LEAP servers (see: https://leap.se/code/issues/2280)
78
79 Deploying
80 -------------------------------
81
82 * If you have any errors during a run, please try to deploy again as this often
83   solves non-deterministic issues that were not uncovered in our testing.
84   Please re-deploy with `leap -v2 deploy` to get more verbose logs and capture
85   the complete output to provide to us for debugging.
86
87 Contributing
88 ================================
89
90 Run rake tests
91 --------------
92
93     cd tests/platform-ci
94     ./setup.sh
95     bundle exec rake lint
96     bundle exec rake syntax
97     bundle exec rake validate
98     bundle exec rake templates
99     bundle exec rake catalog
100
101 Merge requests
102 --------------
103
104 In order to validate the syntax and style guide compliance before you commit,
105 see https://github.com/pixelated-project/puppet-git-hooks#installation
106 Please fork https://0xacab.org/leap/platform to open a merge request,
107 and pick the `Platform runner (greyhound)` at https://0xacab.org/YOUR_USERNAME/platform/runners
108 in order to run a CI build for your merge request.
109
110 Changes
111 ================================
112
113 Read CHANGES.md or run `git log`.
114
115 Authors and Credits
116 ================================
117
118 See contributors:
119
120     git shortlog -es --all
121
122
123 Copyright/License
124 ================================
125
126 Read LICENSE