Installation¶
- Clone the source from GitHub
- Configure the Python environment
- Create configuration files
- Start the service
Clone the source from GitHub¶
Use the standard git clone command:
$ git clone 'https://github.com/cwaldbieser/txcas.git'
Configure the Python environment¶
If you are new to Python, this will probably be the most difficult step. txcas is tested and run on Python v2.7. Older versions (e.g. v2.6) may work, but are not recommended.
You can download Python from the official web site. If you are running some flavor of Linux or BSD, your distribution’s package manager may provide a pre-packaged Python. The official documentation has a helpful Setup and Usage section.
Note
Attention Windows users! In addition to the Python installer available from the official web site, there are some alternative bundles. The ActivePython installer is a great choice for Python on Windows!
Fufilling Dependencies¶
Warning
Fufilling dependencies tends to be where the real pain points in any software installation are felt. I apologize in advance. The good news is that you probably only have to do this once to set up a development environment. If you set up production environments from source, make sure you take good notes if this step isn’t a smooth ride.
The requirements.txt file lists all the Python dependencies for txcas.
Some Python modules may require dependencies on external system libraries which
may vary depending on your platform. Installing all the dependencies manually
is not a fun process.
While there is no silver bullet, a lot of work has been done to make satisfying dependencies a bit more civilized. Your package manager may provide python modules that you can yum install or apt-get install.
I recommend installing dependencies in a Python virtual environment. This keeps all your dependencies isolated from your system Python and any other Python environments you have. There is a handy guide to virtual environments.
Once I have a virtual environment created and activated, I use pip to
install the requirements listed in requirements.txt.
$ pip install -r ./requirements.txt
Ideally, you can sit back and relax while the packages are downloaded from the Python Package Index (PyPi) and installed as if by magic. In practice, sometimes there are unmet dependencies external to Python that pop up. You may not have the traditional build tools for your platform installed. This will cause issues if one of the dependencies needs to build a C-extension, for example.
Missing external libraries is another common issue. Sometimes it will be necessary to install the devel version of a library using your package manager so the header files are available to compile against.
txcas on Raspberry Pi¶
Since you made it this far, here is an interesting tidbit. Using the above technique, I was able to install txcas on a Raspberry Pi! Using the Raspbian image I installed the following system packages usinig apt-get install:
- python-dev
- libffi-dev
- python-virtualenv
- virtualenvwrapper
- vim
- git
- htop
The first 2 were the only actual dependencies I needed to install. The python-virtualenv and virtualenvwrapper packages are just for working with Python virtual environments (see above). vim is my editor of choice when working on a Pi, git is needed to clone the txcas source, and htop is just fun to watch once txcas is up and running!
xubuntu 14.04 Dependencies for txcas¶
Here are the OS packages that needed to be installed on a new xubuntu 14.04 install to build txcas.
- build-essential
- libffi-dev
- libssl-dev
- libxml2-dev
- libxslt1-dev
Create configuration files¶
In the project directory, copy cas.cfg.example to cas.cfg.
Edit the file and change the settings to suit your needs.
Copy cas.tac.example to cas.tac. Edit the file to configure the
endpoint (host, port, SSL options) on which the service will run.:
$ cd txcas
$ cp cas.cfg.example txcas.cfg
$ vim txcas.cfg
$ cp cas.tac.example cas.tac
$ vim cas.tac
Note
The cas.tac file is a Twisted Application Configuration (TAC) file.
It is essentially a Python file used for configuring a Twisted Application.
As such, it needs to conform to Python syntax. The cas.tac file has
deliberately been kept very simple so configuration is not confusing for
users who don’t have a lot of familiarity with Python. Python enthusiasts
should feel free to experiment with adding settings to this file.
See Using the Twisted Application Framework for more information.
You may need to make additional configuration changes depending on the plugins
you enable. For example, if you use the JSON service registry plugin, you
will need to create a service registry file.
serviceRegistry.json.example is included in the project root as a
starting point.
Start the service¶
The service is started and stopped with the twistd program included with the Twisted networking library. This program is used run a Twisted Application. The simplest invocation of this command is to provide the necessary application configuration in a TAC file, which is a regular Python code file.
The twistd command can also to be used to configure services from the command line. In this case, the CAS service can be run as a twistd sub-command, and options specified on the command line will override options specified in configuration files.
Running the Service as a Twisted Application¶
Start the service by invoking the twistd command:
$ twistd -n -y cas.tac
The above command runs the application in the foreground. If you want to run the
service as a daemon (background service), omit the -n option.
Running the Service as a twistd Subcommand¶
You can run the service using the cas subcommand to twistd. Running the service this way allows you to specify options on the command line or inspect the online help.:
$ twistd -n cas
Again, the -n option runs the service in the foreground. To run it as
a daemon process, omit that option. If you specify the --help option
after the cas subcommand, the program will output a list of options.