Welcome to Kala’s documentation!¶
Introduction¶
Kala document management is built to help your organization manage documents.
User Guide¶
Welcome to the Kala documentation. This guide describes the general philosophy of the application, as well as, detailing the specific operations of each section of the application.
Users & Permissions¶
Granting Permissions¶
Permissions in Kala follow the nested approach seen in the previous section. The first level of Permission is the “Create” Permission. This allows a User to create resources at the level that they were given Permission at. For example, if a User has been given “Create” Permission for an Organization, then the User will have the ability to create Projects, Documents and Document Versions within that Organization.
The next level of Permissions is the “Invite” Permission. The “Invite” Permission gives the same Permissions as the “Create” Permission, but also allows the User to invite Users to collaborate at the Organizational, Project, or Document Level. If the User only has “Invite” Permission, then they will only be allowed to give invited Users Permission up to the “Invite” level.
Finally, the “Manage” Permission allow a User to be an Administrator for the resource that the User is being assigned to. The “Manage” Permission has both the “Create” and “Invite” Permissions but also allows the User to modify the attributes of the resource, and perform actions such as Archive and Delete.
If a User is given a specific Permission on the Project level, then these Permissions will also be enforced on the Documents of the Project. For example, if a User is given the “Invite” Permission on a Project, then that User will be able to invite Users to all of the Documents contained within the Project. The User will also be able to “Create” new Documents and Document Versions for that Project.
Similar to the example above, if a User is given “Create” Permission on a Document, then that User will be able to create new Document Versions only for the Document that the User has Permissions for.
Users¶
Every person that requires access to the system must be invited by an administrator or resource owner. Once the user has an email registered with a password, they can then go the login page, which will be the default landing page if the user is not logged in.
The Users page allows a user to view all of the Users that they work with. If you need to know contact information this is the page to look in.
If you are an administrator this page also allows you to Invite Users by clicking the Invite users button, then filling out the user details. Once the form has been submitted successfully, the new user will be sent an email with instructions for creating a password.
The form requires the administrator to fill in the email address, first name, last name, and selecting a Organization that the User will be in, then by clicking on the “Invite User” button, a new User will be created. You can then edit the details of the User by clicking the Users name link. Editing a Person from this page will take you to the “User Details” page, which is described below.
Edit Profile¶
Editing your own profile is the same process as editing other users profile (if you are an administrator). If you click the drop-down in the top right corner of the screen, and click on the “Your Profile” link, you will be taken to your profile. Change the information that needs to be updated and then click the “Update details” button.
Home¶
Once logged in, the user will be presented with the “Home Page”. From this page, the user will see a list of all of the documents that they have worked on recently. In the middle of the page, there is a list of projects that the user has access too.
From the Home Page, one can click on any of the links in the navigation bar. To access Projects and the associated resources, click on the Projects button.
To get information about Users that you are working with, such as email or phone number, you can click on the Users button. The Users section of the application is also where and administrator can create and manage Users, more on this below.
You can also use the search box in the top navigation bar to search for documents based on the document name, the author, tags, and the description text of the document. Using the search box at this level will search over all of the documents that you have permissions to view.
In addition to the search box, there is also the “Add Resources” button in the top right corner (the + button). If you click this button then you can add Organizations and Projects if you have the correct permissions.
Breadcrumbs & Resource Menu¶
When the user has navigated to a particular resource, they will be presented with both a breadcrumb, as well as, a menu at the top of the page. To illustrate, here is what a documents breadcrumb and top menu might look like for a manager.
The breadcrumb shows the containing resources, in this example, the Project and the Organization. These are links that the user can use to navigate to a higher resource quickly, if needed. The top menu shows all of the operations that are available for the resource and current user.
Organizations¶
The Organizations page shows a list of all of the Organizations that your user has permissions to view.
New Organizations¶
If you are an admin you can click the “+ New Organization” button to create a new Organization. You will need to provide at least a name for the new Organization, then you can click the “Create organization” button.
Settings¶
If you would like to update the Organizations details, or give a User Permission to the Organization, click on the name of the Organization on the main page. This will take you to the Organizations settings.
Inviting Users¶
Once you have clicked the Organizations name, you can then Invite Users to the Organization if you have the proper Permissions. After submitting the form, the User will be sent an email with instructions on how to create a password (if they do not already have one). Users can be invited to be a manager by selecting the Manager user type in the drop-down.
Projects¶
The Projects page is where you select which project you would like to work with. When you first start on this page you will be presented with a list of Organizations that you are associated with, and a list of the Projects that you are working on for the Organizations.
If you are a manager (or administrator) you will also be able to create new projects from this page. To create a new Project, you can enter the name of the new Project and select which Organization you want to create the Project under. You must fill out at least the projects name, then click the “Create Project” button and the new Project will be created.
Project Page¶
Once you have selected a Project to work on from the Projects Page, you will be taken to the Project page. This is where you can interact with the Project’s resources. In the Documents tab, you can upload a new Document by choosing the file to upload, the giving the file a description, and optionally add document specific tags. Once you have done this, you can click the “Upload Document” button to upload the new Document.
You can also sort the Documents either by Date - newest to oldest - or you can sort the Documents alphabetically - A to Z -. You will need to click the “Sort Documents” button to have the sorting take effect. You can also filter the Documents by the files type. If you only want to see images in click the “Filter by Category” select box, select images then click “Sort Documents”.
To view a Documents detail click the name of the Document.
If you would like to create a new version of a Document, you can do that from this page as well. To do this, find the Document that you would like to upload a new version to, then click the “Add Version” link. Follow the same instructions for uploading a Document as listed above.
If you are a project manager you can also move the Project to another Organization by using the move feature in the settings section. Click on the “Transfer ownership” and select the Organization that you would like to move the Project to.
Managers can also manage access for the Project by clicking on the “Manage access” link in the navigation bar.
Document Page¶
The Document page will show all of the version for the selected Document. You can also request a zipped copy of all of the version be sent via email by clicking the Download ZIP button.
On the Document page you can upload a new version by clicking the New version button, choose the file, fill out the description, click upload.
Managers can also manage access for the Document by clicking on the “Manage access” link in the navigation bar of the settings page.
The main concept of Kala is a hierarchical layout. At the top of the tree is the Organization. For smaller organizations or businesses there might be only one Organization (as shown in the diagram below) but Kala can be configured to have as many Organizations as you wish. For instance, you may want to give each functional unit it’s own Organization, or perhaps a sub contractor should be an Organization within the application. This guide will attempt to provide suggestions on how to divide the application, but it is left to the users and administrators to find the right balance between Organizations and Projects.
Projects always reside within an Organization. Any permissions given to a User at an Organizational level will be propagated through to all of the Projects in that Organization. Likewise all permissions at the Project level will be passed on to all of the Projects Documents.
Documents are a collection of uploaded artifacts to the application. Documents can have associated Users and Permissions of their own. Each Document also has one or more Versions. Each Version has it’s own metadata, such as who was the User that uploaded the Version, comments about the Version and a timestamp of when the Version was uploaded.
This diagram is a visual representation of how a small business might use Kala to organize their documents. In this example, the business has decided that one Organization “Custom Design Inc” is appropriate. In this case one could image that only upper management would have permissions at the Organization level. There are 3 Projects in this Organization, “Fiscal”, “Engineering”, and “HR”. At the Project level it would be appropriate to give Project Managers, Leads, etc. permissions on the respective Project. At the Document level (the most fine grained) you might invite in house team members to work on a specific document, or maybe a 3rd party contractor would be invited to collaborate on a specific Document, by uploading new version for review.
Admin Guide¶
Manual Ubuntu 16.04 Install¶
Spin up a new EC2 machine (Ubuntu 16.04), it should have a security group with ssh access (your IP/32 is a good rule), http and https open to the world (If that is what you want).
If you want to use S3 [0] and SQS [1], which I recommend, then you should create a bucket for your documents and a queue for background jobs. You will also need an IAM role that has the correct permissions for these resources (the easiest thing to do is grant all access, but up to the user). Attach the IAM role either during the creation of the EC2 machine, or after the machine has booted.
Once the machine is up, run:
git clone https://github.com/bgroff/kala-app.git
sudo mv kala-app/ /srv/
sudo sh /srv/kala-app/deploy/provision/ubuntu.sh
This should get you a running instance of the application, with the two test users described in the README.
You can then edit the deployment environment variables to setup your AWS account information
sudo nano /etc/uwsgi/apps-enabled/{your-ec2-instance-hostname}.ini
Then you can restart uwsgi:
sudo systemctl restart uwsgi
If everything went right, you should now be able to use S3 for document storage.
It is recommended to add an SSL certificate for your install. You can get a free certificate from letsencrypt. Directions are available from the Digital Ocean page [2].