A Docker multi-container application that runs a BOINC server
MIT License
boinc-server-docker
is the easiest way to run your own BOINC server. You can run the server on a Linux machine, in which case the requirements are,
or you can run your server on Windows 7+ or Mac OSX, in which case you should use either,
or, if your Windows/Mac system is too old to support either of those,
There are no other dependencies, as everything else is packaged inside of Docker.
For a full tutorial on creating your own server with boinc-server-docker
, see the project cookbook.
If you are looking to create a server and are already somewhat familiar with Docker and BOINC, the following short description takes you through creating a server and running your own science application.
To check out this repository and get a test server fully up and running, simply run,
git clone https://github.com/marius311/boinc-server-docker.git
cd boinc-server-docker
docker-compose pull
docker-compose up -d
You can now visit the server webpage and connect clients to the server at http://127.0.0.1/boincserver.
Notes:
- The first time you run this, it may take a few minutes after invoking the
docker-compose up -d
command before the server webpage appears.- Make sure your user is added to the
docker
group, otherwise thedocker-compose
anddocker
commands in this guide need to be run withsudo
.- If using Docker Toolbox, replace the final command above with
URL_BASE=$(docker-machine ip) docker-compose up -d
. The server will be accessible at the IP returned bydocker-machine ip
rather than at127.0.0.1
.
The server comes pre-configured to immediately run Docker-based science applications. To do so, first create a Docker container which runs your code. As an example, we will use a python:alpine
image. Suppose your calculation is run with the following command,
docker run python:alpine python -c "print('Hello BOINC')"
To submit a job on the server which runs this as a BOINC job you would first get a shell inside the server,
docker-compose exec apache bash
Then submit the job by running
bin/boinc2docker_create_work.py python:alpine python -c "print('Hello BOINC')"
Now you can connect a BOINC client the server and run this job. Note that to run these types of Docker-based jobs, the client computer will need 64bit Virtualbox installed and "virtualization" enabled in the BIOS.
If your job has output files, have the container write them in /root/shared/results
and they are automatically returned to the server when the job is done.
This is a simple example, but any Docker containers with arbitrary code installed inside of them will work!
To stop the server and delete all server and database files (for example, if you want to start over with a fresh copy), run,
docker-compose down -v
Finally, boinc-server-docker
is not just useful to get a simple test server running, its actually meant to run your real server. To learn how to, read the project cookbook, or look at the Cosmology@Home source code as an example (boinc-server-docker
was in fact originally developed for Cosmology@Home).
Happy crunching!
If you wish to modify and rebuild any of the boinc-server-docker
images yourself, you will need this git repository's submodules checked out. To do so, run git submodule update --init --recursive
from the repository folder, or clone with git clone --recursive
in the first place. Note that building these images is only necessary if you are helping with development of this package; if you wish to build your own project using these base images, follow the instruction in the cookbook instead.
Currently, building the images is only guaranteed to work on Linux. Some users have reported successfully building on Windows or Mac, but this is considered experimental at this point.
Please feel free to contact the maintainers or submit Issues and Pull Requests for this repository if you wish to contribute!
Version 4.1.0 - Oct 20, 2019
Version 4.0.2 - Apr 27, 2019
Version 4.0.1 - Jan 31, 2018
Version 4.0.0 - Jan 18, 2018
Version 3.0.1 - Aug 2, 2018
PROJECT_ROOT
wasn't fully customizableVersion 3.0.0 - July 27, 2018
secrets
, and the procedure for how to deal with them is documented here.boincadm
.BOINC_USER
and PROJECT_ROOT
, and fixed PROJECT
which wasn't fully configurable before. Under the hood, the boinc-server-docker
images now use Docker ONBUILD
instructions to make this happen.docker-compose down -v
and simply start a fresh server with version 3.0.0
. If instead you want to upgrade a project you created with boinc-server-docker v2.x.x
, you should follow these instructions:
Edit the FROM
line in your custom Dockerfiles to source the appropriate 3.0.0
images.
Diff your docker-compose.yml
and .env
files against the corresponding ones in example_project/
, and merge in changes you see (notably, add the secrets
volume).
Run docker-compose build
to build updated images.
Run docker-compose run --rm makeproject bash
and navigate to /home/boincadm/secrets
. This is your secrets
volume, and you should edit the files you see here so that they contain your passwords, keys, etc...
Bring your project down with docker-compose down
.
Run the following to update permissions and upgrade your database:
source .env
eval "$(docker-compose run --rm -T makeproject cat /run/secrets/secrets.env)"
docker-compose run --rm -u root makeproject chown -R $BOINC_USER:$BOINC_USER $PROJECT_ROOT.dst
docker-compose exec mysql mysql_upgrade
docker-compose exec mysql mysqladmin -u root password $DB_PASSWD
Now bring your project back up with docker-compose up -d
.
Version 2.1.0 - May 29, 2018
Version 2.0.0 - Feb 27, 2018
URL_BASE=http//1.2.3.4 PROJECT=myproject docker-compose up -d
. See here and here in the Project Cookbook for more details.$PROJHOME
variable which was previously available in apache
and makeproject
containers has been renamed to $PROJECT_ROOT
to be consistent with the make_tools
script, similarly as with URL_BASE
and PROJECT
, and in anticipation that it too will become configurable.Version 1.4.1 - July 26, 2017
http://127.0.0.1/boincserver
rather than previously when it was http://boincserver.com/boincserver
. This removes the need to edit your /etc/hosts
file on Linux, and on Windows/Mac/docker-machine replaces having to edit /etc/hosts
with the SSH tunnel command above. Related warning: the boincserver.com domain is currently being squatted, so if you're using the old version be careful that you do not type sensitive information into the server website thinking you're interacting with your local test server when in fact it's a remote server at the squatted domain.