source: general/prog/gitserver.xml@ dc905ac

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 dc905ac was dc905ac, checked in by Thomas Trepl <thomas@…>, 10 months ago

Add note about using the daemon; fix $HOME of git user

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

  • Property mode set to 100644
File size: 13.4 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>Introduction</title>
22
23 <para>
24 This section will describe how to set up, administer and secure a
25 <application>git</application> server. <application>Git</application>
26 has many options available. For more detailed documentation see
27 <ulink url="https://git-scm.com/book/en/v2"/>.
28 </para>
29
30 <bridgehead renderas="sect3">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. It 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 server consists of the following steps:
52 </para>
53
54 <sect3>
55 <title>1. Setup Users, Groups, and Permissions</title>
56
57 <para>
58 You will need to be user <systemitem class='username'>root</systemitem>
59 for the initial portion of configuration. Create the <systemitem
60 class="username">git</systemitem> user and group with the following
61 commands:
62 </para>
63
64<screen role="root"><userinput>groupadd -g &gitgid; git &amp;&amp;
65useradd -c "git Owner" -d /home/git -m -g git -s /usr/bin/git-shell -u &gituid; git</userinput></screen>
66
67 <para>
68 Create some files and directories in the home directory of the git user
69 allowing access to the git repository using ssh keys.
70 </para>
71
72<screen role="root"><userinput>install -o git -g git -dm0700 /home/git/.ssh &amp;&amp;
73install -o git -g git -m0600 /dev/null /home/git/.ssh/authorized_keys</userinput></screen>
74
75 <para>
76 For any developer who should have access to the repository
77 add his/her public ssh key to <filename>/home/git/.ssh/authorized_keys</filename>.
78 First, prepend some options to prevent users from using the
79 connection to git for port forwarding to other machines
80 the git server might reach.
81 </para>
82
83<screen role="nodump"><userinput>echo -n "no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty " >> /home/git/.ssh/authorized_keys &amp;&amp;
84cat &lt;user-ssh-key&gt; &gt;&gt; /home/git/.ssh/authorized_keys</userinput></screen>
85
86 <para>
87 It is also useful to set the default name of the initial branch
88 of new repositories by modifying the git configuration. As the
89 <systemitem class='username'>root</systemitem> user, run:
90 </para>
91
92<screen role="nodump"><userinput>git config --global init.defaultBranch trunk</userinput></screen>
93
94 <para>
95 Finally add the <filename>/usr/bin/git-shell</filename> entry to
96 the <filename>/etc/shells</filename> configuration file. This shell
97 has been set in the <systemitem class='username'>git</systemitem>
98 user profile and is to make sure that only git related actions
99 can be executed:
100 </para>
101
102<screen role="root"><userinput>echo "/usr/bin/git-shell" &gt;&gt; /etc/shells</userinput></screen>
103
104 </sect3>
105
106 <sect3>
107 <title>2. Create a git repository</title>
108
109 <para>
110 The repository can be anywhere on the filesystem. It is
111 important that the git user has read/write access to that
112 location. We use <filename class="directory">/srv/git</filename>
113 as base directory. Create a new <application>git</application>
114 repository with the following commands (as the
115 <systemitem class="username">root</systemitem> user):
116 </para>
117
118 <note>
119 <para>
120 In all the instructions below, we use <emphasis>project1</emphasis>
121 as an example repository name. You should name your repository
122 as a short descriptive name for your specific project.
123 </para>
124 </note>
125
126<screen role="root"><userinput>install -o git -g git -m755 -d /srv/git/project1.git &amp;&amp;
127cd /srv/git/project1.git &amp;&amp;
128git init --bare &amp;&amp;
129chown -R git:git .</userinput></screen>
130
131 </sect3>
132
133 <sect3>
134 <title>3. Populate the repository from a client system</title>
135
136 <note>
137 <para>
138 All the instructions in this section and the next should
139 be done on a user system, not the server system.
140 </para>
141 </note>
142
143 <para>
144 Now that the repository is created, it can be used by the
145 developers to put some files into it. Once the ssh key of
146 the user is imported to git's <filename>authorized_keys</filename>
147 file, the user can interact with the repository.
148 </para>
149
150 <para>
151 A minimal configuration should be available on the developer's
152 system specifying its user name and the email address.
153 Create this minimal config file on client side:
154 </para>
155
156<screen role="nodump"><userinput>cat &gt; ~/.gitconfig &lt;&lt;EOF
157[user]
158 name = &lt;users-name&gt;
159 email = &lt;users-email-address&gt;
160EOF</userinput></screen>
161
162 <para>
163 On the developer's machine, setup some files to be pushed
164 to the repository as the initial content:
165 </para>
166
167 <note>
168 <para>
169 The <emphasis>gitserver</emphasis> term used below
170 should be the host name (or ip address) of the git server.
171 </para>
172 </note>
173
174<screen role="nodump"><userinput>mkdir myproject
175cd myproject
176git init --initial-branch=trunk
177git remote add origin git@gitserver:/srv/git/project1.git
178cat &gt;README &lt;&lt;EOF
179This is the README file
180EOF
181git add README
182git commit -m 'Initial creation of README'
183git push --set-upstream origin trunk</userinput></screen>
184
185 <para>The initial content is now pushed to the server and
186 is available for other users. On the current machine, the
187 argument <literal>--set-upstream origin trunk</literal> is
188 now no longer required as the local repository is now
189 connected to the remote repository. Subsequent pushes
190 can be performed as
191 </para>
192
193<screen role="nodump"><userinput>git push</userinput></screen>
194
195 <para>
196 Other developers can now clone the repository and do
197 modifications to the content (as long as their ssh keys
198 has been installed):
199 </para>
200
201<screen role="nodump"><userinput>git clone git@gitserver:/srv/git/project1.git
202cd project1
203vi README
204git commit -am 'Fix for README file'
205git push</userinput></screen>
206
207 <note>
208 <para>
209 This is a very basic server setup based on
210 <application>OpenSSH</application> access. All developers are using
211 the <systemitem class="username">git</systemitem> user to perform
212 actions on the repository and the changes users are commiting can be
213 distiguished as the local user name (see
214 <filename>~/.gitconfig</filename>) is recorded in the
215 changesets.</para>
216 </note>
217
218 <para>
219 Access is restricted by the public keys added to git's
220 <filename>authorized_keys</filename> file and there is no
221 option for the public to export/clone the repository. To
222 enable this, continue with step 4 to set up the git server
223 for public read-only access.
224 </para>
225
226 </sect3>
227
228 <sect3 id="gitserver-init">
229 <title>4. Configure the Server</title>
230
231 <para>
232 The setup described above makes a repository available for
233 authenticated users (via providing the ssh public key file).
234 There is also a simple way to publish the
235 repository to unauthenticated users &mdash; of course without write
236 access.
237 </para>
238
239 <para>
240 The combination of access via ssh (for authenticated users) and
241 the export of repositories to unauthenticated users via the
242 daemon is in most cases enough for a development site.
243 </para>
244
245 <note>
246 <para>
247 The daemon will be reachable at port <literal>9418</literal>
248 by default. Make sure that your firewall setup allows
249 access to that port.
250 </para>
251 </note>
252
253 <para revision="sysv">
254 To start the server at boot time, install the git-daemon
255 bootscript included in the <xref linkend="bootscripts"/> package:
256 </para>
257
258 <indexterm zone="gitserver gitserver-init" revision="sysv">
259 <primary sortas="f-git">git</primary>
260 </indexterm>
261
262<screen role="root" revision="sysv"><userinput>make install-git-daemon</userinput></screen>
263
264 <para revision="systemd">
265 To start the server at boot time, install the
266 <filename>git-daemon.service</filename> unit from the
267 <xref linkend="systemd-units"/> package:
268 </para>
269
270 <indexterm zone="gitserver gitserver-init" revision="systemd">
271 <primary sortas="f-gitserve">gitserve</primary>
272 </indexterm>
273
274<screen role="root" revision="systemd"><userinput>make install-git-daemon</userinput></screen>
275
276 <para>
277 In order to allow <application>git</application> to export a
278 repository, a file named <filename>git-daemon-export-ok</filename>
279 is required in each repository directory on the server. The
280 file needs no content, just its existance enables, its absence
281 disables the export of that repository.
282 </para>
283
284<screen role="root"><userinput>touch /srv/git/project1.git/git-daemon-export-ok</userinput></screen>
285
286 <para revision="sysv">
287 The script to start the git daemon uses some default values
288 internally. Most important is the path to the repository
289 directory which is set to <filename class="directory">/srv/git</filename>.
290 In case you have for whatever reason created the repository in a
291 different location, you'll need to tell the boot script where the
292 repository is to be found. This can be achieved by creating a
293 configuration file named <filename>/etc/sysconfig/git-daemon</filename>.
294 This configuration file will be imported if it exists, meaning it is
295 optional. The file can look like:</para>
296<screen revision="sysv">
297# Begin /etc/sysconfig/git-daemon
298
299# Specify the location of the git repository
300GIT_BASE_DIR="/srv/git/"
301
302# Directories added to whitelist
303DFT_REPO_DIR="$GIT_BASE_DIR"
304
305# Add extra options which will appended to the 'git daemon'
306# command executed in the boot script
307GIT_DAEMON_OPTS=""
308
309# End /etc/sysconfig/git-daemon
310</screen>
311 <para revision="systemd">
312 Along with the <filename>git-daemon.service</filename> unit, a
313 configuration file named <filename>/etc/default/git-daemon</filename>
314 has been installed. Review this configuration file to match your
315 needs.
316 </para>
317
318 <para>
319 There are only three options to set in the configuration file:
320 <itemizedlist>
321 <listitem>
322 <para>
323 GIT_BASE_DIR=&lt;dirname&gt;
324 </para>
325 <para>Specify the location of the repository directory
326 on which the git daemon operates on. Relative pathes
327 in access to the daemon will translated to be relative
328 to this directory.
329 </para>
330 </listitem>
331 <listitem>
332 <para>
333 DFT_REPO_DIR=&lt;dirname&gt;
334 </para>
335 <para>The directory is added to the white list of allowed
336 directories. This variable can hold multible directory
337 names but is usually set equal to <literal>GIT_BASE_DIR</literal>.
338 </para>
339 </listitem>
340 <listitem>
341 <para>
342 GIT_DAEMON_OPTS=&lt;options&gt;
343 </para>
344 <para>In case you have to pass special options to the
345 <command>git daemon</command> command, they have to be
346 specified in this setting. One example might be to adjust
347 the port number where daemon is listening. In this case,
348 add <literal>--port=&lt;port number&gt;</literal> to this variable.
349 For more information about which options can be set, take a look
350 at the output of <command>git daemon --help</command>.
351 </para>
352 </listitem>
353 </itemizedlist>
354 </para>
355
356 <para>
357 After starting the daemon, unauthenticated users can clone exported
358 repositories by using
359 </para>
360<screen role="nodump"><userinput>git clone git://gitserver/project1.git</userinput></screen>
361
362 <para>
363 As the basedir is <filename class="directory">/srv/git</filename> by
364 default (or set to a custom value in the config), <application>git</application>
365 interprets the incoming path (/project1.git) relative to that base
366 directory so that the repository in <filename class="directory">/srv/git/project1.git</filename>
367 is served.
368 </para>
369
370 </sect3>
371
372 </sect2>
373
374</sect1>
Note: See TracBrowser for help on using the repository browser.