Getting Started#

How to run Shapelets server#

Once you have installed shapelets, in order to get started you need user credentials to access the UI, and you need to start the server.

There is an administrator user created directly so that you can log in right after installation. Your credentials are username admin with password admin

You can create new users directly on Python.

>>> import shapelets as sh
>>> sh.register(
>>>     user_name = "usernew",
>>>     password  = "your_pass",
>>>     default   = True      # If you want to set admin user as default for register DataApps with that user.
>>> )

Now, in order to execute the server, run the following command. We will add the --daemon parameter to keep the server running in the background.

>>> shapelets server run --daemon


–daemon param only works on linux systems.

Now you can go to localhost and login.

You can know more about this built-in tool in Configuration wizard.

Configuration wizard#

Shapelets have a toml configuration file called settings.toml. This configuration file have the params to configure the shapelets server.

The shapelets software have a configuration wizard to configure this file. You can execute this wizard by:

>>> shapelets -h
usage: shapelets [-h] {server,client} ...

Shapelets Platform Tools

positional arguments:
    server         Server tools
    client         Client Defaults

optional arguments:
-h, --help       show this help message and exit


Shapelets includes a wizard to manage all aspects related to the shapelets server, such as its configuration or its correct execution. You can execute the shapelets server configuration using:

>>> shapelets server -h
usage: shapelets server [-h] {show,config,run,systemd} ...

positional arguments:
    show                Shows current configuration
    config              Configures server settings
    run                 Runs the server
    systemd             Generates daemon configuration for systemd

optional arguments:
-h, --help            show this help message and exit

What do you can do with this wizard? Check this out!

Check the actual config#

You can check the actual settings using:

>>> usage: shapelets server show [-h] [--plain-passwords] path

positional arguments:
path               Working folder where the settings will be loaded from

optional arguments:
-h, --help         show this help message and exit
--plain-passwords  Show plain passwords

For example, checking the default settings:

>>> shapelets server show .
host = ""
port = 4567
static = "/home/shapelets/lib/python3.8/site-packages/shapelets/svr/www"
loop = "auto"
secret = "**********"
salt = "csAz7ZXZHdLYQZcEpR6rcg=="

protocol = "auto"

protocol = "auto"

enabled = false

path = "~/.shapelets/data.db"
db_schema = "shapelets"

Modify the config#

The shapelets configuration takes into account a lot of important aspects for a correct and safe deployment, you can see here:

>>> shapelets server config -h
usage: shapelets server config [-h] [--host HOST] [--port PORT] [--uds UDS] [--fd FD] [--limit-concurrency LIMIT_CONCURRENCY]
                            [--backlog BACKLOG] [--timeout-keep-alive TIMEOUT_KEEP_ALIVE] [--ssl-keyfile SSL_KEYFILE]
                            [--ssl-certfile SSL_CERTFILE] [--ssl-keyfile-password SSL_KEYFILE_PASSWORD] [--ssl-version SSL_VERSION]
                            [--ssl-cert-reqs SSL_CERT_REQS] [--ssl-ca-certs SSL_CA_CERTS] [--ssl-ciphers SSL_CIPHERS]
                            [--database-path DATABASE_PATH] [--database-temp-directory DATABASE_TEMP_DIRECTORY]
                            [--database-threads DATABASE_THREADS] [--database-memory-limit DATABASE_MEMORY_LIMIT]

Creates a configuration file for a server

positional arguments:
destination           Folder where the settings will be saved

optional arguments:
-h, --help            show this help message and exit
--host HOST           Address to bind the server
--port PORT           Port number of the server
--uds UDS             Unix domain socket
--fd FD               Bind to socket from this file descriptor
--limit-concurrency LIMIT_CONCURRENCY
                        Maximum number of concurrent connections or tasks to allow, before issuing  HTTP 503 responses.
--backlog BACKLOG     Maximum number of connections to hold in backlog.
--timeout-keep-alive TIMEOUT_KEEP_ALIVE
                        Close Keep-Alive connections if no new data is received within this timeout.
--ssl-keyfile SSL_KEYFILE
                        SSL key file
--ssl-certfile SSL_CERTFILE
                        SSL certificate file
--ssl-keyfile-password SSL_KEYFILE_PASSWORD
                        SSL keyfile password
--ssl-version SSL_VERSION
                        SSL version to use
--ssl-cert-reqs SSL_CERT_REQS
                        Whether client certificate is required
--ssl-ca-certs SSL_CA_CERTS
                        CA certificates file
--ssl-ciphers SSL_CIPHERS
                        Ciphers to use
--database-path DATABASE_PATH
                        Path to the file containing the configuration database
--database-temp-directory DATABASE_TEMP_DIRECTORY
                        Temporal directory for result handling and buffering
--database-threads DATABASE_THREADS
                        Maximum number of threads to use in data processing operations
--database-memory-limit DATABASE_MEMORY_LIMIT
                        Maximum memory to use during memory operations.

These settings may be also loaded from the environment, using the same
names of these settings with `shapelets_server` prefix.

For example, if host is not provided by the configuration file,
it will try to resolve its value by reading an environment variable
called `shapelets_server__host` (dashes are converted to

Database settings can also be set through environment settings; for
each of the options offered, the prefix will be `shapelets_database__`,
followed with the name of the property (without `database`).  For
example, `--database-memory-limit` will be looked up in the environment
as `shapelets_database__memory_limit`.

Environment values have lower priority over settings found in
configuration files.

Run the server#

To run the server you can execute run command and server will start with the settings in settings.toml file:

>>> shapelets server run
INFO:     Started server process [1653903]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on (Press CTRL+C to quit)

In addition, you can launch the shapelets server in daemon mode, so that the server will run even if you close your terminal.

>>> shapelets server run --daemon
Running Shapelets as a daemon:
    Lock file: /home/shapelets/shapelets.lock
    Log file : /home/shapelets/shapelets.log
    Pid file : /home/shapelets/
To stop it:
    cat /home/shapelets/ | xargs kill


–daemon param only works on linux systems.

Create a unix service#

Shapelets has a wizard that allows you to quickly set up a unix service to deploy the server.

It also shows you the exact commands to install the service without any problems. You can run it by launching:

>>> shapelets server systemd -h
usage: shapelets server systemd [-h] [-n NAME] [-w WRK] [-u USR] [-g GRP] [-d DST]

Generates a service template that runs a shapelets server using systemd.

optional arguments:
-h, --help            show this help message and exit
-n NAME, --name NAME  Name of the service template
-w WRK, --wrk WRK     Working directory
-u USR, --usr USR     User running the server
-g GRP, --grp GRP     Group to run the server
-d DST, --dst DST     Folder to store the service template (/etc/systemd/system/).

Creating service templates may require sudo permissions, since
it will try to write the template to /etc/systemd/system/

You may change the template destination using argument -d, providing
a folder where to store the template.

To start a server
If the service has been named `shapelets`:

    systemctl enable shapelets
    systemctl daemon-reload
    systemctl start shapelets

To query a server
    systemctl status shapelets

To stop a server
    systemctl stop shapelets

To remove a server
    systemctl disable shapelets
    rm /etc/systemd/system/shapelets.service
    rm /usr/lib/systemd/system/shapelets.service
    systemctl daemon-reload
    systemctl reset-failed


Shapelets has a complete logging system, which allows you to connect from the same machine to different instances of Shapelets. The shapelets client wizard allows you to interact with these configuration features.

You can execute the shapelet client configuration using:

>>> shapelets client -h
usage: shapelets client [-h] (--local | --url URL) [-u USR]
                    [-p PWD] [--create] [--remember-me]

optional arguments:
-h, --help           show this help message and exit
--local              Use Local server
--url URL            URL of the server to connect to
-u USR, --usr USR    User Name
-p PWD, --pwd PWD    User Password
--create             Create user if not exists
--remember-me        Logon and remember credentials

What do you can do with this wizard? Check this out!

Create a new user#

In your local machine.

>>> shapelets client --local -u new_user -p new_user_pass --create

In a remote server

>>> shapelets client --url my_server_remote:myport -u new_user -p new_user_pass --create

Configure the autologin#

In your local machine.

>>> shapelets client --local -u new_user -p new_user_pass --remember-me

In a remote server

>>> shapelets client --url my_server_remote:myport -u new_user -p new_user_pass --remember-me