Gitblit devel
view | history | commit | commitdiff
James Moger
2011-06-01 f1720ca884bc3fa9da1288ad955e46f165aa4168
commit | author | age
1f9dae 1 ## Server Setup and Configuration
dd7961 2
f13c4c 3 1. Download and unzip [Gitblit %VERSION%](http://gitblit.com/%DISTRIBUTION%).<br/>
dd7961 4 *Its best to eliminate spaces in the path name as that can cause troubleshooting headaches.* 
JM 5 2. The server itself is configured through a simple text file.<br/>
6 Open `gitblit.properties` in your favorite text editor and make sure to review and set:
7     - *git.repositoryFolder*
8     - *server.tempFolder*
00afd7 9     - *server.httpBindInterface* and *server.httpsBindInterface*<br/>
JM 10 **NOTE:** Consider using **https** exclusively because passwords for authentication are transmitted as clear text!     
dd7961 11     - *server.storePassword*<br/>
00afd7 12 **NOTE:** The certificate password AND the keystore password must match!     
dd7961 13 3. Execute `gitblit.cmd` or `java -jar gitblit.jar` from a command-line
JM 14 4. Wait a minute or two while all dependencies are downloaded and your self-signed certificate is generated.
15 5. Open your browser to <http://localhost> or <https://localhost> depending on your chosen configuration.
16 6. Click the *Login* link and enter the default administrator credentials: **admin / admin**<br/>
00afd7 17 **NOTE:** Make sure to change the administrator username and/or password!! 
dd7961 18
JM 19 ### Administering Repositories
00afd7 20 Repositories can be created, edited, renamed, and deleted through the web UI.  They may also be created, edited, and deleted from the command-line using real [Git](http://git-scm.com) or your favorite file manager and text editor.
dd7961 21
JM 22 All repository settings are stored within the repository `.git/config` file under the *gitblit* section.
23
24     [gitblit]
25         description = master repository
00afd7 26         owner = james
dd7961 27         useTickets = false
JM 28         useDocs = true
29         showRemoteBranches = false
30         accessRestriction = clone
00afd7 31         isFrozen = false
dd7961 32         
JM 33 #### Repository Names
34 Repository names must be unique and are case-insensitive.  The name must be composed of letters, digits, or `/ _ - .`<br/>
35 Whitespace is illegal.
36
00afd7 37 #### Repository Owner
JM 38 The *Repository Owner* has the special permission of being able to edit a repository through the web UI.  The Repository Owner is not permitted to rename the repository, delete the repository, or reassign ownership to another user.
39
dd7961 40 ### Administering Users
00afd7 41 All users are stored in the `users.properties` file or in the file you specified in `gitblit.properties`.<br/>
dd7961 42 The format of `users.properties` follows Jetty's convention for HashRealms:
JM 43
44     username,password,role1,role2,role3...
45
46 #### Usernames
47 Usernames must be unique and are case-insensitive.<br/>
48 Whitespace is illegal.
49
50 #### Passwords
56c549 51 User passwords are CASE-SENSITIVE and may be *plain* or *md5* formatted (see `gitblit.properties` -> *realm.passwordStorage*).
dd7961 52
JM 53 #### User Roles
f13c4c 54 There is only one actual *role* in Gitblit and that is *#admin* which grants administrative powers to that user.  Administrators automatically have access to all repositories.  All other *roles* are repository names.  If a repository is access-restricted, the user must have the repository's name within his/her roles to bypass the access restriction.  This is how users are granted access to a restricted repository.
dd7961 55
JM 56 ### Creating your own Self-Signed Certificate
57
00afd7 58 Review the contents of the `makekeystore.cmd` or `makekeystore_jdk.cmd` script and execute it.<br/>
JM 59 **NOTE:** The certificate password AND the keystore password must match!
dd7961 60
JM 61 ### Running as a Service
f13c4c 62 Review the contents of the `installService.cmd` or `installService64.cmd`, as appropriate for your installed Java Virtual Machine.<br/>
JM 63 Set the *JVM* variable in the script to the location of your Java Virtual Machine, add any necessary start parameters, and execute the script.
dd7961 64
JM 65 #### Command-Line Parameters
66     --tempFolder           Server temp folder
67     --repositoriesFolder   Git Repositories Folder
68     --realmFile            Users Realm Hash File
69     --useNio               Use NIO Connector else use Socket Connector.
70     --httpPort             HTTP port for to serve. (port <= 0 will disable this connector)
71     --httpsPort            HTTPS port to serve.  (port <= 0 will disable this connector)
72     --storePassword        Password for SSL (https) keystore.
73     --shutdownPort         Port for Shutdown Monitor to listen on. (port <= 0 will disable this monitor)
74     
75 **Example**
76
1f9dae 77     java -jar gitblit.jar --realmFile c:\myrealm.txt --storePassword something
JM 78     
79 ## Client Setup and Configuration
80 ### Https with Self-Signed Certificates
81 You must tell Git not to verify the self-signed certificate in order to perform any remote Git operations.
82
83 - Eclipse/EGit
84     1. Window->Preferences->Team->Git->Configuration
85     2. Click the *New Entry* button
86     3. <pre>Key = *http.sslVerify*       
87        Value = *false*</pre>
88 - Command-line Git ([Git-Config Manual Page](http://www.kernel.org/pub/software/scm/git/docs/git-config.html))
89     <pre>git-config --global --bool --add http.sslVerify false</pre>
90
91 ### Cloning an Access Restricted Repository 
92 - Eclipse/Egit<br/>Nothing special to configure, EGit figures out everything.
93     <pre>https://yourserver/git/your/repository</pre>
94 - Command-line Git<br/>*My testing indicates that your username must be embedded in the url.  YMMV.*
95     <pre>https://username@yourserver/git/your/repository</pre>
96