source: general/prog/gitserver.xml@ 5362771

10.1 11.0 ken/refactor-virt lazarus qt5new trunk xry111/git-date xry111/git-date-for-trunk xry111/git-date-test
Last change on this file since 5362771 was 5362771, checked in by Thomas Trepl <thomas@…>, 11 months ago

Update gitserver page, add bootscript (sysv/systemd)

git-svn-id: svn://svn.linuxfromscratch.org/BLFS/trunk/BOOK@24071 af4574ff-66df-0310-9fd7-8a98e5e911e0

  • Property mode set to 100644
File size: 8.8 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6 <!ENTITY gitgid "58">
7 <!ENTITY gituid "58">
8]>
9
10<sect1 id="gitserver" xreflabel="Running a git Server">
11 <?dbhtml filename="gitserver.html"?>
12
13 <sect1info>
14 <othername>$LastChangedBy$</othername>
15 <date>$Date$</date>
16 </sect1info>
17
18 <title>Running a git Server</title>
19
20 <sect2 role="package">
21 <title>Running a git Server</title>
22
23 <para>
24 This section will describe how to set up, administer and secure
25 a <application>git</application> server. It is recommended to
26 have a look to the <ulink url="https://git-scm.com/book/en/v2">git-scm documentation</ulink>
27 as <application>git</application> has many options to set.
28 </para>
29
30 <bridgehead renderas="sect3">git Server Dependencies</bridgehead>
31
32 <bridgehead renderas="sect4">Required</bridgehead>
33 <para role="required">
34 <xref linkend="git"/> and
35 <xref linkend="openssh"/>
36 </para>
37
38 </sect2>
39
40 <sect2 role="configuration">
41 <title>Setting up a git Server.</title>
42
43 <para>
44 The following instructions will install a
45 <application>git</application> server, which will be set
46 up to use <application>OpenSSH</application> as the secure
47 remote access method.
48 </para>
49
50 <para>
51 Configuration of the <application>git</application> server
52 consists of the following steps:
53 </para>
54
55 <sect3>
56 <title>1. Setup Users, Groups, and Permissions</title>
57
58 <para>
59 You'll need to be user
60 <systemitem class='username'>root</systemitem> for the
61 initial portion of configuration. Create the <systemitem
62 class="username">git</systemitem> user and group with the
63 following commands:
64 </para>
65
66<screen role="root"><userinput>groupadd -g &gitgid; git &amp;&amp;
67useradd -c "git Owner" -d /home/git -m -g git -s /usr/bin/git-shell -u &gituid; git</userinput></screen>
68
69 <para>
70 Create some files and directories in the home directory
71 of the git user. The current approach is to allow access
72 to the git repository using ssh keys.
73 </para>
74
75<screen role="root"><userinput>install -o git -g git -dm0700 /home/git/.ssh &amp;&amp;
76install -o git -g git -m0600 /dev/null /home/git/.ssh/authorized_keys
77</userinput></screen>
78
79 <para>
80 For any developer who should have access to the repository
81 add his/hers public ssh key to <filename>/home/git/.ssh/authorized_keys</filename>.
82 Prepending some options to prevent users to use the
83 connection to git for port forwarding to other machines
84 the git server might reach.
85 </para>
86
87<screen role="nodump"><userinput>echo -n "no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty " >> /home/git/.ssh/authorized_keys &amp;&amp;
88cat users-ssh-key >> /home/git/.ssh/authorized_keys</userinput></screen>
89
90 </sect3>
91
92 <sect3>
93 <title>2. Create a git repository.</title>
94
95 <para>
96 The repository can be but has not to be in git users home
97 directory - it can be anywhere on the filesystem. It is
98 important that the git user has read/write access to that
99 location. We use <filename class="directory">/srv/git</filename>
100 as base directory. Create a new <application>git</application>
101 repository with the following commands (as the
102 <systemitem class="username">root</systemitem> user):
103 </para>
104
105<screen role="root"><userinput>install -o git -g git -m0755 -d /srv/git/project1.git &amp;&amp;
106cd /srv/git/project1.git &amp;&amp;
107git init --bare &amp;&amp;
108chown -R git:git .</userinput></screen>
109
110 <para>
111 Now that the repository is created, it can be used by the
112 developers to put some files into it. Once the ssh key of
113 the user is imported to git's <filename>authorized_keys</filename>
114 file, the user can interact with the repository.
115 </para>
116
117 <para>
118 A minimal configuration should be available on developers
119 machine specifying its user name and the email address.
120 Create this minimal config file on client side:
121 </para>
122
123<screen role="nodump"><userinput>cat &gt; ~/.gitconfig &lt;&lt;EOF
124[user]
125 name = &lt;users-name&gt;
126 email = &lt;users-email-address&gt;
127EOF</userinput></screen>
128
129 <para>On the developers machine, setup some files to be pushed
130 to the repository as the initial content:
131 </para>
132
133<screen role="nodump"><userinput>mkdir myproject
134cd myproject
135git init
136git remote add origin git@gitserver:/srv/git/project1.git
137cat &gt;README &lt;&lt;EOF
138This is the README file
139EOF
140git add README
141git commit -m 'Initial creation of README'
142git push --set-upstream origin master</userinput></screen>
143
144 <para>The initial content is now pushed to the server and
145 is available for other users. On the current machine, the
146 argument <literal>--set-upstream origin master</literal> is
147 now no longer required as the local repository is now
148 connected to the remote repository. Subsequent pushes
149 can be performed as
150 </para>
151
152<screen role="nodump"><userinput>git push</userinput></screen>
153
154 <para>
155 Other developers can now clone the repository and do
156 modifications to the content (as long as their ssh keys
157 has been installed):
158 </para>
159
160<screen role="nodump"><userinput>git clone git@gitserver:/srv/git/project1.git
161cd project1
162vi README
163git commit -am 'Fix for README file'
164git push</userinput></screen>
165
166 <note>
167 <para>
168 This is a very basic server setup based on <application>OpenSSH</application>
169 access. All developers are using the <systemitem
170 class="username">git</systemitem> user to perform actions
171 on the repository and the changes users are commiting can
172 be distiguished as the local user name (see
173 <filename>~/.gitconfig</filename>) is recorded in the
174 changesets.</para>
175 </note>
176
177 <para>Access is restricted by the public keys added to git's
178 <filename>authorized_keys</filename> file and there is no
179 option for the public to export/clone the repository. To
180 enable this, continue with step 3 to setup the git server.
181 </para>
182
183 </sect3>
184
185 <sect3>
186 <title>3. Configure the Server</title>
187
188 <para>
189 The setup described above makes a repository available for
190 authenticated users (via providing the ssh public key file).
191 There is also a quite simple server to publish the
192 repository to unauthenticated users - of course without write
193 access.
194 </para>
195 <para>
196 The combination of access via ssh (for authenticated users) and
197 the export of repositories to unauthenticated users via the
198 daemon is in most cases enough for a development site.
199 </para>
200
201 <note>
202 <para>
203 The daemon will be reachable at port <literal>9418</literal>
204 by default. Make sure that your firewall setup allows
205 access to that port.
206 </para>
207 </note>
208
209 </sect3>
210
211 <sect3 id="gitserver-init">
212 <title>4. Starting the Server</title>
213
214 <para revision="sysv">
215 To start the server at boot time, install the git-daemon
216 bootscript included in the <xref linkend="bootscripts"/> package:
217 </para>
218
219 <para revision="systemd">
220 To start the server at boot time, install the
221 <filename>git-daemon.service</filename> unit from the
222 <xref linkend="systemd-units"/> package:
223 </para>
224
225 <indexterm zone="gitserver gitserver-init" revision="sysv">
226 <primary sortas="f-git">git</primary>
227 </indexterm>
228
229<screen role="root" revision="sysv"><userinput>make install-git-daemon</userinput></screen>
230
231 <indexterm zone="gitserver gitserver-init" revision="systemd">
232 <primary sortas="f-gitserve">gitserve</primary>
233 </indexterm>
234
235<screen role="root" revision="systemd"><userinput>make install-git-daemon</userinput></screen>
236
237 <para>
238 In order to make <application>git</application> exporting a
239 repository, a file named <filename>git-daemon-export-ok</filename>
240 is required in each repository directory on the server. The
241 file needs no content, just its existance enables, its absence
242 disables the export of that repository.
243 </para>
244
245<screen role="root"><userinput>touch /srv/git/project1.git/git-daemon-export-ok</userinput></screen>
246
247 <para>
248 Also review the configuration file
249 <filename revision="sysv">/etc/sysconfig/git-daemon</filename>
250 <filename revision="systemd">/etc/default/git-daemon</filename>
251 for valid repository paths.
252 </para>
253
254 </sect3>
255
256 </sect2>
257
258</sect1>
Note: See TracBrowser for help on using the repository browser.