Commit 1f8fbcfa authored by frnmst's avatar frnmst
Browse files

Merge branch 'dev'

parents bb206ce9 98b00a34
# Ignore everything except the repository related stuff.
*
!kalliope_docker.py
!README.md
!LICENSE.txt
!kalliope_docker_asciinema.json
!kalliope_docker.conf.dist
# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
......
# Makefile
#
# Copyright (c) 2017-2018, Franco Masotti
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.
default: pep doc test
githook:
git config core.hooksPath .githooks
pep:
yapf --style '{based_on_style: pep8; split_before_logical_operator: False}' -i kalliope_docker/*.py tests/*.py
flake8 --ignore=F401,E501 kalliope_docker/*.py tests/*.py
doc:
$(MAKE) -C docs html
install:
pip install .
test:
python setup.py test
uninstall:
pip uninstall kalliope_docker
dist:
python setup.py sdist
python setup.py bdist_wheel
upload:
twine upload dist/*
clean:
rm -rf build dist *.egg-info
.PHONY: default pep doc install test uninstall dist upload clean
# Kalliope Docker Debian
Run [Kalliope](https://kalliope-project.github.io/) inside a Debian Docker container
[![asciicast](https://asciinema.org/a/145756.png)](https://asciinema.org/a/145756)
# Table of contents
[](TOC)
- [Kalliope Docker Debian](#kalliope-docker-debian)
- [Table of contents](#table-of-contents)
- [Reasons](#reasons)
- [Features](#features)
- [Notes](#notes)
- [How to](#how-to)
- [Dependencies](#dependencies)
- [TODO](#todo)
- [Copyright and License](#copyright-and-license)
[](TOC)
## Reasons
- Debian-based distros are not your daily GNU/Linux distributions.
- Deploy Kalliope in a matter of minutes.
## Features
- Audio I/O
- Shared directory
- Edit configuration
- Network access
- LAN, using LAN addresses directly
- Internet
- No proprietary dependencies (notably: no `libttspico-utils`)
### Notes
- Containers for this image are run in ephemeral mode. this means that
one the container is stopped, it is automatically deleted. This is
possible since we use a shared voulme for the files.
- You should edit your profile to use espeak as the default TTS since
it's the only free software offline engine available for the moment.
Installation of svox is not supported because it's proprietary software.
- Once you have defined the profile and resources git links, these will be
already configured when Kalliope starts. The purpose is to separate
completely the profile from the other components such as the neurons
so that the user always works with a clean and more manageable profile.
## How to
1. Copy `kalliope_docker.conf.dist` to `kalliope_docker.conf`
2. Edit it based on your needs. Variables are self explanatory.
3. Then:
$ ./kalliope_docker.py setup generate
$ ./kalliope_docker.py image create
$ ./kalliope_docker.py container run
If no errors are reported, Kalliope should be ready for orders.
### Dependencies
- Docker (system)
- Git (system)
- Python 3 (system)
- PYaml (Python)
## TODO
- Code refactoring
- Full documentation on Sphinx
- Create kalliope:kalliope unprivileged user and group.
- `kalliope start` must be run by kalliope:kalliope and access the
shared volumes only.
- Use the logger module instead of `print` to print the status of the current
operation.
- Check if there is full network access.
## Copyright and License
Copyright (c) 2017, Franco Masotti <franco.masotti@student.unife.it>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Kalliope Docker
===============
A Python script that downloads, runs, builds and handles the voice controlled
personal assistant Kalliope_ inside a Debian Docker container.
.. _Kalliope: https://kalliope-project.github.io/
Video
-----
.. image:: https://asciinema.org/a/145756.png
:target: https://asciinema.org/a/145756
:align: center
Documentation
-------------
https://frnmst.github.io/kalliope-docker
Copyright and License
---------------------
Copyright (C) 2017-2018 frnmst (Franco Masotti) <franco.masotti@live.com>
<franco.masotti@student.unife.it>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SPHINXPROJ = kalliope_docker
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
Cache files
===========
Definition
----------
Cache files are copies of resources and profiles used by kalliope-docker.
They include the files mounted as volumes by the Docker container.
Paths
-----
All cache files for kalliope-docker lie in ``~/.cache/kalliope-docker``.
# -*- coding: utf-8 -*-
#
# Configuration file for the Sphinx documentation builder.
#
# This file does only contain a selection of the most common options. For a
# full list see the documentation:
# http://www.sphinx-doc.org/en/stable/config
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
sys.path.insert(0, os.path.abspath('..'))
# -- Project information -----------------------------------------------------
project = 'kalliope_docker'
copyright = '2018, Franco Masotti'
author = 'Franco Masotti'
# The short X.Y version
version = ''
# The full version, including alpha/beta/rc tags
release = ''
# -- General configuration ---------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.coverage',
'sphinx.ext.githubpages',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path .
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
html_theme_options = {
'github_user': 'frnmst',
'github_repo': 'kalliope-docker',
'github_banner': True,
}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# The default sidebars (for documents that don't match any pattern) are
# defined by theme itself. Builtin themes are using these templates by
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
html_sidebars = {
'**': [
'about.html',
'navigation.html',
'relations.html', # needs 'show_related': True theme option to display
'searchbox.html',
'donate.html',
]
}
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'kalliope_dockerdoc'
# -- Options for LaTeX output ------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'kalliope_docker.tex', 'kalliope\\_docker Documentation',
'Franco Masotti', 'manual'),
]
# -- Options for manual page output ------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'kalliope_docker', 'kalliope_docker Documentation',
[author], 1)
]
# -- Options for Texinfo output ----------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'kalliope_docker', 'kalliope_docker Documentation',
author, 'kalliope_docker', 'One line description of project.',
'Miscellaneous'),
]
# -- Extension configuration -------------------------------------------------
Configuration File
==================
The configuration file must lie in:
::
~/.config/kalliope_rest/kalliope_rest.conf
What follows is an example of configuration file which is included in
this repository
::
# An example configuration file.
[Profile]
# Directory where all the cache will lie. Defaults to ~/.cache/kalliope-docker
# with ~ being expanded to /home/<user>.
# Base directory full path = /home/user/.cache/kalliope-docker
# Kalliope's profile.
Git url = https://github.com/kalliope-project/kalliope_starter_en.git
[Resources]
# Put your neurons, stt or tts.
r1 git url = https://github.com/Ultchad/kalliope-espeak.git
r2 git url = https://github.com/kalliope-project/kalliope_neuron_wikipedia.git
# you can put as many resources as you want.
[Environment]
Timezone = America/New_York
[Docker]
Docker image tag = kalliope-docker
Dockerfile = Dockerfile
# This is the directory containing the files used by the docker image.
# Its path is under the "Base directory full path".
Docker image files directory = kalliope-shared
# The name of the home directory that is used inside the container.
Container shared home directory = /home/kalliope
Debian version = stretch
[CMU Sphinx]
language1 = it-IT
Copyright and License
=====================
Copyright (C) 2017-2018 frnmst (Franco Masotti) <franco.masotti@live.com>
<franco.masotti@student.unife.it>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
.. kalliope_docker documentation master file, created by
sphinx-quickstart on Sat May 12 22:18:16 2018.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to kalliope_docker's documentation!
===========================================
.. toctree::
:maxdepth: 2
:caption: Contents:
install
configuration_file
cache_files
running
notes
copyright_license
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
Installation
============
Run the following command in either a root or normal terminal (depending on
your Python setup) from the root directory of the project's cloned repository,
::
pip install .
or simply
::
make install
All the necessary dependencies should be installed automatically along with
the program.
Distribution packages
---------------------
- None
Dependencies
------------
- Python 3.x
- PYaml_
- Docker_
- Git_
.. _PYaml: http://pyyaml.org/wiki/PyYAML
.. _Docker: https://www.docker.com/
.. _Git: http://git-scm.com/
Notes
=====
- Containers for this image run in ephemeral mode. This means that
one the container is stopped, it is automatically deleted. This is
possible since we use a shared voulme for the files.
- You should edit your profile to use espeak as the default TTS, since
it is the only free software offline engine available for the moment.
Installation of svox (``libttspico-utils``) is not supported because it
is proprietary software. If you use svox, you will need to adjust the
``settings.yml`` file in your profile to support espeak instead.
- Once you have defined the profile and resources git links, these will be
already configured when Kalliope starts. The purpose is to separate
completely the profile from the other components such as the neurons
so that the user always works with a clean and more manageable profile.
Reasons to use this script
--------------------------
- Debian-based distros are not your daily GNU/Linux distributions.
- Deploy Kalliope in a matter of minutes with all your resources, such as
neurons, stt and tts engines already configured.
- The target directory generated by kalliope_docker can be used as a Kalliope
profile on a bare metal installation.
Features
--------
- Audio I/O
- Shared directory
- Editable configuration
- Network access
- LAN, using LAN addresses directly
- Internet
- No proprietary dependencies, notably: no ``libttspico-utils``. Only the
hotword detector ``Snowboy`` has proprietary components and it is the
only one supported for the moment.
See https://github.com/MycroftAI/mycroft-precise/wiki/Software-Comparison
</
Running
=======
1. Copy ``kalliope_docker.conf.dist`` to ``~/.conf/kalliope_docker.conf``
2. Edit it based on your needs. Variables are self explanatory.
3. Then:
::
$ kalliope_docker setup download
$ kalliope_docker image build
$ kalliope_docker container run -i
You must then start Kalliope with
::
$ kalliope start
It might take a while to build the docker image. If no errors are reported,
Kalliope should be ready for orders after the last command.
As a service
------------
Once you are sure that Kalliope works as expected you can run the Docker
container in the background. This will also start Kalliope automatically:
::
$ kalliope_docker container run