source: general/prog/gitserver.xml@ d6de80b

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 d6de80b was d6de80b, checked in by Bruce Dubbs <bdubbs@…>, 9 months ago

Still more tweaks

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

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