What is Sloecode?
Sloecode is an open source project, hosted on launchpad.net that aims to provide a comprehensive, installable code forge. A "code forge" is a set of tools that help groups of people write software (think sourceforge, launchpad etc). It typically includes a revision control system, and optionally project wikis, bug tracking, issue tracking, feature planning and any other features people might need. However, it's important to note that we're not trying to replicate Launchpad! Launchpad is a great service, and we don't want to compete with it. Instead, we're providing a tool for people who:
- Don't want their code to be public - either because it's commercial software or because it's not ready yet. You can use sloecode in your business, college, university without having to release your software to the wider world. You can do this on launchpad, but you must pay for the privilege. The project was borne out of the need to have a code forge for an educational environment: putting students' work online is not an option.
- Want their code forge system to be hosted locally. For large code bases, the communication times between a local machine and the central launchpad.net servers can become expensive - especially in locations where the Internet connection is poor. Running sloecode is easy (as we'll see soon) and gives you complete control over the system. You're are responsible for server maintenance, backup, and general administration.
Compared to Launchpad, we're aiming for a completely different user base.
How does it Work?
Sloecode is made up of two distinct parts:
The Bazaar/SSh smart server is a python-twisted application that understands the SSH protocol, and runs bzr-serve on demand for users. Every time you interact with the server using a Bazaar client application you're actually talking to the smart server. We need this component for several reasons: first, we don't want users to require a system account on the Linux server (which is the usual way of setting up a Bazaar server), but we do still want to use SSH public/private key authentication. This means the SSH server needs to know about our database and be able to retrieve keys from it on demand.
The Sloecode Web App is the front-end for the whole system. It's written in pylons, and makes use of a whole host of other libraries including jinja2 (page templates), formencode (input validation), YUI3 (javascript components), repoze.what and repoze.who (authorisation and authentication), and a whole lot more. The web-app provides control for managers and administrators to create projects and users and assign users to projects (with different levels of access). Regular users can see basic information about their bazaar branches (both personal repositories and project repositories), and manage their SSH keys.
The plan for the future is to add optional components - the key word being optional. One of our design goals is to make sloecode easy to install; this includes minimising install-time dependancies.
The key thing to understand about Sloecode is that we're not writing the VCS ourselves - we're simply making Bazaar easier to install and manage.
Enough already, give me the server!
Sloecode has not yet been released, but you are welcome to participate in testing. To set up the server, you'll first need the sloecode PPA in your sources.list. To achieve this, run the following command:
Then update your package lists:
You can now install the sloecode server package:
The server package should install all the package dependancies. However, before you can run the server, you need to set up the database back-end. The default back-end us sqlite, which is fine for testing or for very low-use installations. Sloecode uses sqlalchemy, which allows us to use any number of databse backends. This, and many other configuration details can be edited by tweaking this file:
Once you're happy with the settings, you need to create the database tables. Do this by running:
This command will read the values present in the configuration file, and create the default database tables for you. You only need to run this command once (to create the tables in your database)!
If you have edited any of the other values, you will want to restart the server:
By default, log files are in /var/log/sloecode, Bazaar repositories are created in
and the default database is a simple SQLite file (which won't handle any kind of heavy workload or concurrency, so you may wish to change that). The RSA public/private key pair the smart server uses to communicate with clients are stored in
And the clients?
Client setup is much simpler. Simply follow these steps:
That's it! Everything is all set up. Now you can start using the sloecode server.
Bazaar / Sloecode Basics
I won't cover the details of how to use Bazaar. If you need that instruction, look at the official Bazaar documentation. However, here are a few pointers:
The Sloecode Web App is the front-end for the whole system. It's written in pylons, and makes use of a whole host of other libraries including jinja2 (page templates), formencode (input validation), YUI3 (javascript components), repoze.what and repoze.who (authorisation and authentication), and a whole lot more. The web-app provides control for managers and administrators to create projects and users and assign users to projects (with different levels of access). Regular users can see basic information about their bazaar branches (both personal repositories and project repositories), and manage their SSH keys.
The plan for the future is to add optional components - the key word being optional. One of our design goals is to make sloecode easy to install; this includes minimising install-time dependancies.
The key thing to understand about Sloecode is that we're not writing the VCS ourselves - we're simply making Bazaar easier to install and manage.
Enough already, give me the server!
Sloecode has not yet been released, but you are welcome to participate in testing. To set up the server, you'll first need the sloecode PPA in your sources.list. To achieve this, run the following command:
sudo add-apt-repository ppa:sloecode
Then update your package lists:
sudo apt-get update
You can now install the sloecode server package:
sudo apt-get install sloecode
The server package should install all the package dependancies. However, before you can run the server, you need to set up the database back-end. The default back-end us sqlite, which is fine for testing or for very low-use installations. Sloecode uses sqlalchemy, which allows us to use any number of databse backends. This, and many other configuration details can be edited by tweaking this file:
/etc/default/sloecode-production.ini
Once you're happy with the settings, you need to create the database tables. Do this by running:
sudo paster setup-app /etc/default/sloecode-production.ini
This command will read the values present in the configuration file, and create the default database tables for you. You only need to run this command once (to create the tables in your database)!
If you have edited any of the other values, you will want to restart the server:
sudo service sloecode restart
By default, log files are in /var/log/sloecode, Bazaar repositories are created in
/srv/sloecode/bzr-repos
and the default database is a simple SQLite file (which won't handle any kind of heavy workload or concurrency, so you may wish to change that). The RSA public/private key pair the smart server uses to communicate with clients are stored in
/var/sloecode/keys
And the clients?
Client setup is much simpler. Simply follow these steps:
- Make sure you have an account created for you in the sloecode web interface. Log in to the web interface with your username and password.
- Click on the "Manage SSH Keys" link on your home page. You need to paste your SSH public key in the form provided. This allows your Bazaar client to authenticate with the sloecode server. If you don't have an SSH key, you can generate one by running:
ssh-keygen
and view the public key by running:
cat ~/.ssh/id_rsa.pub
- All client machines need the 'bzr' and 'bzr-sloecode' packages installed. Assuming you have the sloecode PPA installed (see instructions for doing this in the server section, above), you can run:
sudo apt-get install bzr bzr-sloecode
- Finally, you need to tell the Bazaar sloecode plugin where the sloecode server is. The client plugin looks for an environment variable called "SLOECODE_SERVER", and will complain if it is not found. The easiest way to set this environment variable is to edit your "~/.bashrc" file and add this line to the end:
export SLOECODE_SERVER=domain.of.your.server.com
The value of this variable should be either a domain name, OR an IP address that points to the sloecode server you wish to use. For example, if the server is installed on the local network you might have the following:
export SLOECODE_SERVER=192.168.1.10
Note that you must not add any network protocol specification - the sloecode client plugin takes care of that for you. If you are running the sloecode ssh service on a port other than 22, you must add this port to the end of the string, like so:
export SLOECODE_SERVER=192.168.1.10:4022
- Finally, if your username on the sloecode server is different from your local computer username, you need to tell the Bazaar sloecode plugin what username it should use. To do this, run the command:
bzr sc-login sloecode_username
Where "sloecode_username" is the username you use to log in to the sloecode web interface. For example, on my machine the command is:
bzr sc-login thomir
If you run the command without a username it will tell you what username is currently set.
That's it! Everything is all set up. Now you can start using the sloecode server.
Bazaar / Sloecode Basics
I won't cover the details of how to use Bazaar. If you need that instruction, look at the official Bazaar documentation. However, here are a few pointers:
- Every user on the sloecode server has a personal repository. To push code to your personal repository, do this:
bzr push sc:~sloecode_username/branch_name
By default personal repositories are created with no branches, so whenever you push or pull from a personal repository you must always specify a branch name!
- Personal repositories are private - you are the only one who can read or write to your personal repository. If you need to share your code with someone else, you need to store it in a project repository.
- To pull code from a project repository, the command looks like this:
bzr pull sc:project_name/branch_name
Note that there is no tilde character before the project name. Also note that you need not specify the branch name if you want the special branch called "trunk". For example, if I want a copy of the trunk branch of project "elastic", I'd run the following command:
bzr pull sc:elastic
However if I want a specific branch called "fix-bug-1234", I'd run the following:
bzr pull sc:elastic/fix-bug-1234
Final Thoughts:
We're still writing sloecode - it's an ongoing effort and won't be finished any time soon. We welcome your feedback - the best way to contact is us via the sloecode-developers mailing list, or in the #sloecode channel on freenode IRC, or leave a comment below. Have we missed anything? Spot any bugs? Have suggestions for improvements/future direction? We'd love to hear from you!
We're still writing sloecode - it's an ongoing effort and won't be finished any time soon. We welcome your feedback - the best way to contact is us via the sloecode-developers mailing list, or in the #sloecode channel on freenode IRC, or leave a comment below. Have we missed anything? Spot any bugs? Have suggestions for improvements/future direction? We'd love to hear from you!
Posts
View Thomi Richards's profile