source: general/prog/gitserver.xml@ dc905ac

10.1 11.0 11.1 11.2 lazarus plabs/python-mods qt5new trunk upgradedb xry111/intltool xry111/soup3 xry111/test-20220226
Last change on this file since dc905ac was dc905ac, checked in by Thomas Trepl <thomas@…>, 2 years ago

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

git-svn-id: svn:// af4574ff-66df-0310-9fd7-8a98e5e911e0

  • Property mode set to 100644
File size: 13.4 KB
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6 <!ENTITY gitgid "58">
7 <!ENTITY gituid "58">
10<sect1 id="gitserver" xreflabel="Running a Git Server">
11 <?dbhtml filename="gitserver.html"?>
13 <sect1info>
14 <othername>$LastChangedBy$</othername>
15 <date>$Date$</date>
16 </sect1info>
18 <title>Running a Git Server</title>
20 <sect2 role="package">
21 <title>Introduction</title>
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=""/>.
28 </para>
30 <bridgehead renderas="sect3">Server Dependencies</bridgehead>
32 <bridgehead renderas="sect4">Required</bridgehead>
33 <para role="required">
34 <xref linkend="git"/> and
35 <xref linkend="openssh"/>
36 </para>
38 </sect2>
40 <sect2 role="configuration">
41 <title>Setting up a Git Server</title>
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>
50 <para>
51 Configuration of the server consists of the following steps:
52 </para>
54 <sect3>
55 <title>1. Setup Users, Groups, and Permissions</title>
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>
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>
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>
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>
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>
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>
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>
92<screen role="nodump"><userinput>git config --global init.defaultBranch trunk</userinput></screen>
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>
102<screen role="root"><userinput>echo "/usr/bin/git-shell" &gt;&gt; /etc/shells</userinput></screen>
104 </sect3>
106 <sect3>
107 <title>2. Create a git repository</title>
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>
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>
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>
131 </sect3>
133 <sect3>
134 <title>3. Populate the repository from a client system</title>
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>
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>
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>
156<screen role="nodump"><userinput>cat &gt; ~/.gitconfig &lt;&lt;EOF
158 name = &lt;users-name&gt;
159 email = &lt;users-email-address&gt;
162 <para>
163 On the developer's machine, setup some files to be pushed
164 to the repository as the initial content:
165 </para>
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>
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
181git add README
182git commit -m 'Initial creation of README'
183git push --set-upstream origin trunk</userinput></screen>
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>
193<screen role="nodump"><userinput>git push</userinput></screen>
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>
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>
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>
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>
226 </sect3>
228 <sect3 id="gitserver-init">
229 <title>4. Configure the Server</title>
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>
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>
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>
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>
258 <indexterm zone="gitserver gitserver-init" revision="sysv">
259 <primary sortas="f-git">git</primary>
260 </indexterm>
262<screen role="root" revision="sysv"><userinput>make install-git-daemon</userinput></screen>
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>
270 <indexterm zone="gitserver gitserver-init" revision="systemd">
271 <primary sortas="f-gitserve">gitserve</primary>
272 </indexterm>
274<screen role="root" revision="systemd"><userinput>make install-git-daemon</userinput></screen>
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>
284<screen role="root"><userinput>touch /srv/git/project1.git/git-daemon-export-ok</userinput></screen>
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
299# Specify the location of the git repository
302# Directories added to whitelist
305# Add extra options which will appended to the 'git daemon'
306# command executed in the boot script
309# End /etc/sysconfig/git-daemon
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>
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>
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>
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>
370 </sect3>
372 </sect2>
Note: See TracBrowser for help on using the repository browser.