source: general/prog/gitserver.xml@ 7a8cc527

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

Add 'Running a git server' page

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

  • Property mode set to 100644
File size: 10.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>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 compination 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 <para>
210 As user <systemitem class='username'>root</systemitem> do:
211 </para>
212
213<screen role="root" revision="sysv"><userinput>cat &gt; /etc/rc.d/init.d/git-daemon &lt;&lt;"EOF"
214#!/bin/sh
215########################################################################
216# Begin /etc/rc.d/init.d/git-daemon
217#
218# Description : Start/Stop git as a daemon
219#
220# Authors :
221#
222# Version : LFS x.x
223#
224# Notes :
225#
226########################################################################
227
228### BEGIN INIT INFO
229# Provides: git-daemon
230# Required-Start: network
231# Should-Start:
232# Required-Stop:
233# Should-Stop:
234# Default-Start:
235# Default-Stop:
236# Short-Description: git as daemon
237# Description:
238# X-LFS-Provided-By:
239### END INIT INFO
240
241. /lib/lsb/init-functions
242
243GIT_BIN="/usr/bin/git"
244DFT_REPO_DIR="/srv/git/"
245PID_FILE="/run/git-daemon.pid"
246
247case "${1}" in
248 start)
249 log_info_msg "Starting git-daemon ..."
250 $GIT_BIN daemon \
251 --detach --pid-file=$PID_FILE \
252 --user=git --group=git \
253 --reuseaddr --base-path=$DFT_REPO_DIR $DFT_REPO_DIR
254 evaluate_retval
255 ;;
256
257 stop)
258 log_info_msg "Stopping git-daemon ..."
259 killproc -p $PID_FILE $GIT_BIN
260 evaluate_retval
261 ;;
262
263 restart)
264 ${0} stop
265 sleep 1
266 ${0} start
267 ;;
268
269 *)
270 echo "Usage: ${0} {start|stop|restart}"
271 exit 1
272 ;;
273esac
274
275exit 0
276
277# End /etc/rc.d/init.d/git-daemon
278EOF
279chmod 755 /etc/rc.d/init.d/git-daemon
280ln -v -sf ../init.d/git-daemon /etc/rc.d/rc0.d/K29git-daemon
281ln -v -sf ../init.d/git-daemon /etc/rc.d/rc1.d/K29git-daemon
282ln -v -sf ../init.d/git-daemon /etc/rc.d/rc2.d/K29git-daemon
283ln -v -sf ../init.d/git-daemon /etc/rc.d/rc3.d/S50git-daemon
284ln -v -sf ../init.d/git-daemon /etc/rc.d/rc4.d/S50git-daemon
285ln -v -sf ../init.d/git-daemon /etc/rc.d/rc5.d/S50git-daemon
286ln -v -sf ../init.d/git-daemon /etc/rc.d/rc6.d/K29git-daemon</userinput></screen>
287
288<screen role="root" revision="systemd"><userinput>cat &gt; /etc/systemd/system/git-daemon.service &lt;&lt;EOF
289[Unit]
290Description=Start Git Daemon
291
292[Service]
293ExecStart=/usr/bin/git daemon --reuseaddr --base-path=/srv/git/ /srv/git/
294
295Restart=always
296RestartSec=500ms
297
298StandardOutput=syslog
299StandardError=syslog
300SyslogIdentifier=git-daemon
301
302User=git
303Group=git
304
305[Install]
306WantedBy=multi-user.target
307EOF</userinput></screen>
308 <para revision="systemd">
309 Enable and start the daemon be executing
310 </para>
311<screen role="root" revision="systemd"><userinput>systemctl enable git-daemon &amp;&amp;
312systemctl start git-daemon</userinput></screen>
313 <para revision="sysv">
314 Start the daemon be executing
315 </para>
316<screen role="root" revision="sysv"><userinput>/etc/rc.d/init.d/git-daemon start</userinput></screen>
317
318 <para>
319 In order to make <application>git</application> exporting a
320 repository, a file named <filename>git-daemon-export-ok</filename>
321 is required in each repository directory on the server. The
322 file needs no content, just its existance enables, its absence
323 disables the export of that repository.
324 </para>
325
326<screen role="root"><userinput>touch /srv/git/project1.git/git-daemon-export-ok</userinput></screen>
327
328 </sect3>
329
330 </sect2>
331
332</sect1>
Note: See TracBrowser for help on using the repository browser.