source: general/prog/gitserver.xml@ c4908df

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 c4908df was c4908df, checked in by Thomas Trepl <thomas@…>, 2 years ago

Remove bootscript, add git-shell paragraph

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

  • Property mode set to 100644
File size: 9.6 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 to use 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<screen role="root"><userinput>install -o git -g git -m755 -d /srv/git/project1.git &amp;&amp;
120cd /srv/git/project1.git &amp;&amp;
121git init --bare &amp;&amp;
122chown -R git:git .</userinput></screen>
123
124 </sect3>
125
126 <sect3>
127 <title>3. Populate the repository from a client system</title>
128
129 <para>
130 Now that the repository is created, it can be used by the
131 developers to put some files into it. Once the ssh key of
132 the user is imported to git's <filename>authorized_keys</filename>
133 file, the user can interact with the repository.
134 </para>
135
136 <para>
137 A minimal configuration should be available on the developer's
138 system specifying its user name and the email address.
139 Create this minimal config file on client side:
140 </para>
141
142<screen role="nodump"><userinput>cat &gt; ~/.gitconfig &lt;&lt;EOF
143[user]
144 name = &lt;users-name&gt;
145 email = &lt;users-email-address&gt;
146EOF</userinput></screen>
147
148 <para>
149 On the developer's machine, setup some files to be pushed
150 to the repository as the initial content:
151 </para>
152
153<screen role="nodump"><userinput>mkdir myproject
154cd myproject
155git init --initial-branch=trunk
156git remote add origin git@gitserver:/srv/git/project1.git
157cat &gt;README &lt;&lt;EOF
158This is the README file
159EOF
160git add README
161git commit -m 'Initial creation of README'
162git push --set-upstream origin trunk</userinput></screen>
163
164 <para>The initial content is now pushed to the server and
165 is available for other users. On the current machine, the
166 argument <literal>--set-upstream origin trunk</literal> is
167 now no longer required as the local repository is now
168 connected to the remote repository. Subsequent pushes
169 can be performed as
170 </para>
171
172<screen role="nodump"><userinput>git push</userinput></screen>
173
174 <para>
175 Other developers can now clone the repository and do
176 modifications to the content (as long as their ssh keys
177 has been installed):
178 </para>
179
180<screen role="nodump"><userinput>git clone git@gitserver:/srv/git/project1.git
181cd project1
182vi README
183git commit -am 'Fix for README file'
184git push</userinput></screen>
185
186 <note>
187 <para>
188 This is a very basic server setup based on
189 <application>OpenSSH</application> access. All developers are using
190 the <systemitem class="username">git</systemitem> user to perform
191 actions on the repository and the changes users are commiting can be
192 distiguished as the local user name (see
193 <filename>~/.gitconfig</filename>) is recorded in the
194 changesets.</para>
195 </note>
196
197 <para>
198 Access is restricted by the public keys added to git's
199 <filename>authorized_keys</filename> file and there is no
200 option for the public to export/clone the repository. To
201 enable this, continue with step 4 to setup the git server.
202 </para>
203
204 </sect3>
205
206 <sect3 id="gitserver-init">
207 <title>4. Configure the Server</title>
208
209 <para>
210 The setup described above makes a repository available for
211 authenticated users (via providing the ssh public key file).
212 There is also a quite simple way to publish the
213 repository to unauthenticated users - of course without write
214 access.
215 </para>
216
217 <para>
218 The combination of access via ssh (for authenticated users) and
219 the export of repositories to unauthenticated users via the
220 daemon is in most cases enough for a development site.
221 </para>
222
223 <note>
224 <para>
225 The daemon will be reachable at port <literal>9418</literal>
226 by default. Make sure that your firewall setup allows
227 access to that port.
228 </para>
229 </note>
230
231 <para revision="sysv">
232 To start the server at boot time, install the git-daemon
233 bootscript included in the <xref linkend="bootscripts"/> package:
234 </para>
235
236 <indexterm zone="gitserver gitserver-init" revision="sysv">
237 <primary sortas="f-git">git</primary>
238 </indexterm>
239
240<screen role="root" revision="sysv"><userinput>make install-git-daemon</userinput></screen>
241
242 <para revision="systemd">
243 To start the server at boot time, install the
244 <filename>git-daemon.service</filename> unit from the
245 <xref linkend="systemd-units"/> package:
246 </para>
247
248 <indexterm zone="gitserver gitserver-init" revision="systemd">
249 <primary sortas="f-gitserve">gitserve</primary>
250 </indexterm>
251
252<screen role="root" revision="systemd"><userinput>make install-git-daemon</userinput></screen>
253
254 <para>
255 In order to make <application>git</application> exporting a
256 repository, a file named <filename>git-daemon-export-ok</filename>
257 is required in each repository directory on the server. The
258 file needs no content, just its existance enables, its absence
259 disables the export of that repository.
260 </para>
261
262<screen role="root"><userinput>touch /srv/git/project1.git/git-daemon-export-ok</userinput></screen>
263
264 <para>
265 Also review the configuration file
266 <filename revision="sysv">/etc/sysconfig/git-daemon</filename>
267 <filename revision="systemd">/etc/default/git-daemon</filename>
268 for valid repository paths.
269 </para>
270
271 </sect3>
272
273 </sect2>
274
275</sect1>
Note: See TracBrowser for help on using the repository browser.