diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 250 |
1 files changed, 250 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..70c1b60 --- /dev/null +++ b/README.md @@ -0,0 +1,250 @@ +Image docker Gitolite/cgit +========================= + +This [Docker][docker] image offers a very quick way of deploying a Gitolite / Cgit server. Gitolite is a lightweight yet powerful git manager. Cgit is web-based frontend to Git repositories. + + + +## Starting a gitolite-cgit container + +### First launch + +This first launch will create the server RSA keypair and make Gitolite initialization. `SSH_KEY` is the Gitolite admin's public RSA key. +For more details about Gitolite setup, please read the [official documentation][gitolite_doc]. + +The container will stop by itself once the initial configuration is done. The `--rm` will make Docker remove it automatically. Only data will remain on the volume/bindmount. + + $ docker run --rm -dit -v git-data:/home/git -e SSH_KEY="$(cat /home/<user>/.ssh/id_rsa.pub)" gjbs84/gitolite-cgit:latest + +Default behavion is to save data into an internal named volume, `git-data` in this exemple. Of course you can change it if you wish. + +If it's suits you better you can use a bindmount. Here an exemple with `/srv/git-data`. No existing `repositories` directory must be there ! + + $ docker run --rm -dit -v /srv/git-data:/home/git -e SSH_KEY="$(cat /home/<user>/.ssh/id_rsa.pub)" gjbs84/gitolite-cgit:latest + + +### Troubleshooting + +If the initial startup fails, it can be usefull to repeat it one more time without the `--rm` option. + +The container will remains in stoped state and its logs will be available. + + $ docker logs git-test + +A good first startup looks like this : + +```sh + Generating public/private rsa key pair. + Your identification has been saved in /etc/ssh/ssh_host_rsa_key + Your public key has been saved in /etc/ssh/ssh_host_rsa_key.pub + The key fingerprint is: + SHA256:4GcKIlWTPI5tpto3eqfHK30jBqM8U+eWoTp/tWSU2zs root@67dc97f12dd3 + The key's randomart image is: + +---[RSA 3072]----+ + | .o. | + | .+. | + | .+ .. . | + | .. =. .o | + |. .+. ..So | + | ...+.o+= . | + | + o O.* . . | + |. B * % + E | + | oXoX.+ . . | + +----[SHA256]-----+ + Generating public/private dsa key pair. + Your identification has been saved in /etc/ssh/ssh_host_dsa_key + Your public key has been saved in /etc/ssh/ssh_host_dsa_key.pub + The key fingerprint is: + SHA256:M5WtzLCBRcU6HtrRdBgOHvDkqa+DU3x5XaWC6VjXexU root@67dc97f12dd3 + The key's randomart image is: + +---[DSA 1024]----+ + | .o*ooo | + | B =+o. E.| + | . B+++.. o.| + | .=B=.o + .| + | ..+SO+o o ..| + | +.*oo . . .| + | o ... . | + | o .. | + | ... | + +----[SHA256]-----+ + Starting sshd + Initialized empty Git repository in /home/git/repositories/gitolite-admin.git/ + Initialized empty Git repository in /home/git/repositories/testing.git/ + WARNING: /home/git/.ssh missing; creating a new one + (this is normal on a brand new install) + WARNING: /home/git/.ssh/authorized_keys missing; creating a new one + (this is normal on a brand new install) + First launch : container is now shut down +``` + +## Final launch + +You can now run the final container. It will use the previoulsy created volume `git-data`. Now we can give a name to this container and we have to NAT ports 22 et 80 to the host. Of course you may have to adapt the command line to your network. + + $ docker run --name gitolite-cgit-srv -dit -v git-data:/home/git -p 20080:80 -p 20022:22 gjbs84/gitolite-cgit:lastest + +If you have chosen the bindmount way (here `/srv/git-data`) : + + $ docker run --name gitolite-cgit-srv -dit -v /srv/git-data:/home/git -p 20080:80 -p 20022:22 gjbs84/gitolite-cgit:lastest + +It's now time to check if everythings is right ! Let's clone the `testing` repository. + +If you are new to Gitolite you have to know that every connection to it is made by the same user, commonly `git`. A very convenient way to proceed is to add an entry in your `~/.ssh/config` : + + Host <server> + Port 20022 + User git + IdentityFile ~/.ssh/id_rsa + +Of course you have to adapt this to your network once again. + +Now you can easily clone the testing repo : + + $ git clone localhost:testing + Cloning into 'testing'... + Enter passphrase for key '/home/greg/.ssh/id_rsa': + warning: warning: You appear to have cloned an empty repository. + Checking connectivity... done. + +Git tells us this an empty repository, it's true so everything is fine so far. + +## Updating / recreating container + +If you have deleted the exiting container or wish to update it with a newer version, just run the "Final launch" step again. The server RSA key will change but all your data are kept in Docker volume (or bindmount) . + +### .htaccess authentication + +You may wish to protect access to the git fronted Cgit. + +Just give fill up environnement variables `HTTP_AUTH_USER` and `HTTP_AUTH_PASSWORD` during the final launch step : + + $ docker run --name gitolite-cgit-srv -dit -v git-data:/home/git -p 20080:80 -p 20022:22 -e HTTP_AUTH_USER="my_user" -e HTTP_AUTH_PASSWORD="my_password" gjbs84/gitolite-cgit:latest + + +### Troubleshooting + +If you're experimenting some issue, start with having a loog into running container. Check health of `httpd` and `sshd` daemons. + +To jump into the container : + + $ docker exec -ti git-test sh + +Then check for `sshd` and `httpd` : + +``` + $ ps + PID USER TIME COMMAND + 1 root 0:00 /usr/local/bin/dumb-init -- sh -c prepare-container.sh && exec httpd-foreground + 6 root 0:00 httpd -DFOREGROUND + 13 root 0:00 sshd: /usr/sbin/sshd [listener] 0 of 10-100 startups + 69 daemon 0:00 httpd -DFOREGROUND + 70 daemon 0:00 httpd -DFOREGROUND + 71 daemon 0:00 httpd -DFOREGROUND + 72 daemon 0:00 httpd -DFOREGROUND + 73 daemon 0:00 httpd -DFOREGROUND +``` + +## Using Gitolite and Cgit + +### Cgit + +Cgit is configured to automatically serve every repositories located into `/home/git/repositories` which is where Gitolite stores them. You basically have nothing to do to use it, just got to (adapt URL to the port number and server name) : + + http(s)://myserver:20080 + +You may want to custumize it (clone-prefix, favicon, headers...), just edit `/home/git/cgitrc`. + + +### Gitolite + +This is not a Git/Gitolite course, but here is a very simple set of commands to quickly add a new repo to Gitolite. And a new non-admin user in the process. + +1. Clone the `gitolite-admin` repository : + + $ git clone myserver:gitolite-admin + +2. Edit the `conf/gitolite.conf` file to add a repo : + + repo new_repo + RW+ = bob + +3. Add Bob's public RSA key in `keydir/bob.pub` (of course you can use `admin` which already exists but it's not recommanded...). That's all you have to do to add a Gitolite user. + +4. Add, commit and push the updated Gitolite configuration : + + $ git add keydir/bob.pub conf/gitolite.conf + $ git commit -m "Added Bob and new_repo" + $ git push --all + +5. Now just add a remote site in you local `new_repo` repository and push a local branch to it ! + + $ git remote add origin ssh://myserver:new_repo.git + $ git push origin master + + +For more details, you'll have to check for official documentation of both projects ! + + * [Gitolite][gitolite_admin] administration + * [Cgit][cgit_page] + + +## Add existing repositories + +First you must have an archive containing all you existing repositories. + +They have to be BARE repositories ! No working copy should exist in any of them ! + +1. Jump into the container + +2. Copy repos archive into the container. + + $ scp user@<your_host_local_ip>:/home/user/repos.tgz /tmp/ + +3. Untar archive into Gitolite repositories directory : + + $ cd /home/git/repositories + $ tar -xf /tmp/repos.tgz + $ rm /tmp/repos.tgz + +4. Set permissions : + + $ chown -R git:git * + $ chmod -R 755 * + +5. From now you definitely should read [the official procedure][gitolite_existing_repo] before you go any further ! These commands come directly from there. + + $ su git + $ cd + $ gitolite compile + $ gitolite setup --hooks-only + $ gitolite trigger POST_COMPILE + +6. Clone the Gitolite admin repository or go to your local copy and update the `gitolite.conf` with your new repositories info. Don't forget to add new users public key in `keydir` if needed. + +7. Add/commit/push and you're done ! Check everything is fine with the `info` command. You shoud see all the repositories you have access to, which means all of them (because you have the admin key). + + $ ssh git@myserver info + +8. Adjust Cgit configuration in `/home/git/cgitrc` if you wish, but it will work out of the box. + + +## Building container image + +In case you want to build you own image, clone from Github and build using the common Docker way (adjust or remove proxy settings according to your needs). + + $ docker build --build-arg HTTP_PROXY=http://192.168.0.1:3128 -t <image_name> . + + +## Voir aussi + +* [Base image I used (httpd 2.4) ](https:https://hub.docker.com/_/httpd) +* [Gitolite image](http://github.com/sitaramc/gitolite#adding-users-and-repos) +* [Cgit image](https://github.com/invokr/docker-cgit) +* [Gitolite Documentation](https://gitolite.com/gitolite/index.html) + +[docker]: https://www.docker.com/ +[gitolite_doc]: https://gitolite.com/gitolite/install.html +[gitolite_admin]: https://gitolite.com/gitolite/basic-admin.html +[cgit_page]: https://git.zx2c4.com/cgit/about/ +[gitolite_existing_repo]: https://gitolite.com/gitolite/basic-admin.html#appendix-1-bringing-existing-repos-into-gitolite |