Running conan_server

conan_server is a free and open source server that implements conan remote repositories. It is a very simple application, bundled with the regular conan client installation. For most cases, it is recommended to use the free Artifactory Community Edition for C/C++ server, check Artifactory Community Edition for C/C++ for more information.

Running the simple open source conan_server that comes with the conan installers (or pip packages) is simple. Just open a terminal and type:

$ conan_server

Note

On Windows, you might experience problems with the server, if you run it under bash/msys. It is better to launch it in a regular cmd window.

This server is mainly for testing (though it might work fine for small teams). If you need a more stable, responsive and robust server, you should run it from source:

Running from source (linux)

The conan installer includes a simple executable conan_server for a server quick start. But you can use the conan server through the WSGI application, which means that you can use gunicorn to run the app, for example.

First, clone the conan repository from source and install the requirements:

$ git clone https://github.com/conan-io/conan.git
$ cd conan
$ git checkout master
$ pip install -r conans/requirements.txt
$ pip install -r conans/requirements_server.txt
$ pip install gunicorn

Run the server application with gunicorn. In the following example we will run server on port 9300 with 4 workers and a timeout of 5 minutes (300 seconds, for large uploads/downloads, you can also decrease it if you don’t have very large binaries):

$ gunicorn -b 0.0.0.0:9300 -w 4 -t 300 conans.server.server_launcher:app

Note

Please note the timeout of -t 300 seconds, 5 minutes parameter. If your transfers are very large or in a slow network, you might need to increase that value.

You can also bind to an IPV6 address or specify both IPv4 and IPv6 addresses:

$ gunicorn -b 0.0.0.0:9300 -b [::1]:9300 -w 4 -t 300 conans.server.server_launcher:app

Server configuration

Your server configuration lives in ~/.conan_server/server.conf. You can change values there, prior to launching the server. Note that the server is not reloaded when the values are changed. You have to stop and restart it manually.

The server configuration file is by default:

[server]
jwt_secret: MnpuzsExftskYGOMgaTYDKfw
jwt_expire_minutes: 120

ssl_enabled: False
port: 9300
public_port:
host_name: localhost

store_adapter: disk
authorize_timeout: 1800

# Just for disk storage adapter
disk_storage_path: ~/.conan_server/data
disk_authorize_timeout: 1800

updown_secret: NyiSWNWnwumTVpGpoANuyyhR


[write_permissions]
# "opencv/2.3.4@lasote/testing": default_user,default_user2

[read_permissions]
# opencv/1.2.3@lasote/testing: default_user default_user2
# By default all users can read all blocks
*/*@*/*: *

[users]
demo: demo

Server parameters

Note

Conan server from v1.1 supports relative URLs, so you can avoid setting host_name, public_port and ssl_enabled. The URLs used to upload/download packages will be automatically generated in the client following the URL of the remote. It allows to access the conan server from different networks.

port: Port where conan_server will run.
The client server authorization is done with JWT. jwt_secret is a random string used to generate authentication tokens. You can change it safely anytime (in fact it is a good practice), the change will just force users to log in again. jwt_expire_minutes is the amount of time that users remain logged-in within the client without having to introduce their credentials again.

Other parameters (not recommended from Conan 1.1, but necessary for previous versions):

host_name If you set host_name you must use the machine’s IP where you are running your server (or domain name), something like host_name: 192.168.1.100. This IP (or domain name) has to be visible (and resolved) by the conan client, so take it in account if your server has multiple network interfaces.
public_port Which might be needed if running virtualized, docker or any other kind of port redirection. Files uploads/downloads are served with their own URLs, generated by the system, so the file storage backend is independent. Those URLs need the public port they have to communicate from the outside. If you leave it blank, it will use the port value.

Example: Use conan_server in a docker container that internally runs in the 9300 port but it exposes the 9999 port (where the clients will connect to):
docker run ... -p9300:9999 ... # Check Docker docs for that
server.conf
[server] ssl_enabled: False port: 9300 public_port: 9999 host_name: localhost
ssl_enabled Conan doesn’t handle the SSL traffic by itself, but you can use a proxy like nginx to redirect the SSL traffic to your conan server. If your conan clients are connecting with “https” set ssl_enabled to True. This way conan_server will generate the upload/download urls with “https” instead of “http”.

Note

Important: Conan client, by default, will validate the server SSL certificates and won’t connect if it’s not valid. If you have self signed certificates you have two options:

Use the conan remote command to disable the SSL certifate checks. e.j: conan remote add/update myremote https://somedir False
Append the server .crt file contents to ~/.conan/cacert.pem file.

Check the section How to manage SSL (TLS) certificates section to know more about it.

Conan has implemented an extensible storage backend, based on the abstract class StorageAdapter. Currently the server only supports storage in disk. The folder in which uploaded packages are stored (i.e., the folder you would want to backup) is defined in disk_storage_path.

The storage backend might use a different channel, and uploads/downloads are authorized up to a maximum of authorize_timeout seconds. The value should be enough so large downloads/uploads are not rejected, but not too big to prevent hanging up the file transfers. The value disk_authorize_timeout is not currently used. File transfers are authorized with their own tokens, generated with the secret updown_secret. This value should be different from the above jwt_secret.

Running conan server with SSL using nginx

server.conf

[server]
port: 9300

nginx conf file

server {
    listen 443;
    server_name myservername.mydomain.com;

    location / {
      proxy_pass http://0.0.0.0:9300;
    }
    ssl on;
    ssl_certificate /etc/nginx/ssl/server.crt;
    ssl_certificate_key /etc/nginx/ssl/server.key;
}

remote configuration in Conan client

$ conan remote add myremote https://myservername.mydomain.com/subdir

Running conan server with SSL using nginx in a subdirectory

server.conf

[server]
port: 9300

nginx conf file

server {

       listen 443;
       ssl on;
       ssl_certificate /usr/local/etc/nginx/ssl/server.crt;
       ssl_certificate_key /usr/local/etc/nginx/ssl/server.key;
       server_name myservername.mydomain.com;

       location ~/subdir/(.*)$ {
          proxy_pass http://0.0.0.0:9300/$1;
       }
  }

remote configuration in Conan client

$ conan remote add myremote https://myservername.mydomain.com/subdir

Running conan server using Apache

You need to install mod_wsgi. If you want to use Conan installed from pip, the conf file should be roughly as follows:

Apache conf file (e.j /etc/apache2/sites-available/0_conan.conf)
<VirtualHost *:80>
    WSGIScriptAlias / /usr/local/lib/python2.7/dist-packages/conans/server/server_launcher.py
    WSGICallableObject app
    WSGIPassAuthorization On

    <Directory /usr/local/lib/python2.7/dist-packages/conans>
        Require all granted
    </Directory>
</VirtualHost>
If you want to use Conan checked out from source in, say, /srv/conan, the conf file should be as follows:

Apache conf file (e.j /etc/apache2/sites-available/0_conan.conf)
<VirtualHost *:80>
    WSGIScriptAlias / /srv/conan/conans/server/server_launcher.py
    WSGICallableObject app
    WSGIPassAuthorization On

    <Directory /srv/conan/conans>
        Require all granted
    </Directory>
</VirtualHost>
The directive WSGIPassAuthorization On is needed to pass the HTTP basic authentication to Conan.

Also take into account that the server config files are located in the home of the configured Apache user, e.j var/www/.conan_server, so remember to use that directory to configure your conan server.

Permissions parameters

By default, the server configuration is: Read can be done anonymous, but uploading requires registered users. Users can be easily registered in the [users] section, defining a pair of login: password for each one. Yes, plain text passwords at the moment, but as the server is on-premises (behind firewall), you just need to trust your sysadmin :)

If you want to restrict read/write access to specific packages, configure it in the [read_permissions] and [write_permissions] sections. These sections allow a sequence of patterns and allowed users, in the form:

# use a comma-separated, no-spaces list of users
package/version@user/channel: allowed_user1,allowed_user2

E.g.:

*/*@*/*: * # allow all users to all packages
PackageA/*@*/*: john,peter # allow john and peter access to any PackageA
*/*@project/*: john # Allow john to access any package from the "project" user

The rules are evaluated in order, if the left side of the pattern matches, the rule is applied and it will not look further.

Authentication

Conan provides by default a simple user: password users list in the server.conf file.

There is also a plugin mechanism for setting other authentication methods. The process to install any of them is a simple 2 step process:

Copy the authenticator source file into the .conan_server/plugins/authenticator folder
Add custom_authenticator: authenticator_name in the server.conf [server] section

This is a list of available authenticators, visit their URLs to get them, but also to report issues and collaborate:

htpasswd: Use your server Apache htpasswd file to authenticate users. Get it: https://github.com/d-schiffner/conan-htpasswd
LDAP: Use your LDAP server to authenticate users. Get it: https://github.com/uilianries/conan-ldap-authentication

Create your own custom Authenticator

If you want to create your own Authenticator, create a python module in ~/.conan_server/plugins/authenticator/my_authenticator.py

Example:

def get_class():
    return MyAuthenticator()


class MyAuthenticator(object):
    def valid_user(self, username, plain_password):
        return username == "foo" and plain_password == "bar"

The module has to implement:

A factory function get_class() that returns a class with a valid_user() method instance.
The class containing the valid_user() that has to return True if the user and password are valid or False otherwise.

Got any doubts? Please check out our FAQ section or write us.