timestrap-django

1{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Timestrap \u00b6 Time tracking you can host anywhere. Full export support in multiple formats and easily extensible. Warning \u00b6 This app is currently very unstable. Everything may, and probably will, change. All migrations are going to be wiped and setup properly before release 1.0 so you will not be able to upgrade to 1.0 from early development. Documentation \u00b6 For more details and screenshots check out our main docs website: https://timestrap.bythewood.me/ Superuser Credentials \u00b6 All installations and the demo create a superuser to get you started, if this is a production deployment you will want to change these. Username: admin Password: admin Docker Installation \u00b6 This creates a minimal docker server setup for Timestrap. This currently is in development and may not have persistent data without fiddling. Any help to improve the docker configuration files would be appreciated. Docker Requirements \u00b6 Docker Docker Compose Docker Compose is used for running multiple containers since we require a PostgreSQL database and, not yet but soon, a Redis server for messages and events. Docker Running \u00b6 Make sure to update the environmental variables in docker-compose.yml and check the timestrap/settings/docker.py file to see if you'd like to change anything then run: sudo docker-compose up --detach To migrate the database, create your first superuser, and create the initial site configuration you then need to run: sudo docker - compose exec web python3 manage . py migrate -- settings = timestrap . settings . docker The Timestrap application should now be running on port 80 of whatever system you ran these commands on, if you ran this locally then that would be http://localhost/ . Docker Data \u00b6 All data should be stored in the timestrap_db volume. If you wish to rebuild Timestrap at the latest you can do the following from the timestrap repo you cloned: git pull sudo docker - compose stop sudo docker - compose build sudo docker - compose up -- detach sudo docker - compose exec web python3 manage . py migrate -- settings = timestrap . settings . docker All data will be kept during this process and you'll have the latest version of Timestrap. Development Installation \u00b6 If you'd like to contribute code to Timestrap you'll need to do this! Development Requirements \u00b6 Python 3.5+ Python Dev Node 8+ pipenv npm Firefox geckodriver Python 3.5+ is required because we use async/await with Channels to support WebSockets and add realtime updates to the client. Python Dev is not required on macOS but if you are on Linux, like Ubuntu, you will need to install it with sudo apt install python3-dev . Node 8+ isn't exactly required, you might be able to get away with an older version and we only use node for building the client. You'll probably need to install pipenv with pip, run pip install pipenv to get this. It's just a better python package manager that allows us to lock our dependencies. Node installs npm by default but you may want to install the latest with npm install --global npm . Firefox is used for functional/selenium tests in conjunction with geckodriver, you can get geckodriver from mozilla's offical releases or you might be able to install it with your systems package manager. Brew on macOS has this with brew install geckodriver . If you have to download it manually make sure to extract it in some sort of bin directory e.g. /usr/local/bin/ . Development Setup \u00b6 Once you have all of the above you can get started! For the global npm install on gulp-cli you may need to run this with sudo depending on how you installed everything above. npm install --global gulp-cli npm install pipenv install --dev After all the dependencies install you can migrate the database and run the server. gulp manage:migrate gulp If you'd like to have some sample data to work with you can run gulp manage:fake after you run gulp manage:migrate . Timestrap should now be running at http://localhost:8000 and gulp + django's test server will automatically recognize and recompile changes to any file allowing for quick modification and review. Once you've made your changes you can test with gulp coverage:development and if that is successful and you want to share your changes create a pull request ! Development Commands \u00b6 I've prebuilt a variety of build commands for development, you can see a list of them by running gulp --tasks and I will briefly cover some of them here. gulp Will run a webserver with django and build the client with webpack gulp lint Will check all code for style consistency gulp manage:makemigrations Will generate new migrations if models changes gulp manage:migrate Makes sure there is a superuser, runs migrations gulp manage:fake Adds a bunch of fake data for testing gulp manage:reset Resets the database and adds fake data with a superuser gulp coverage:development Lints, runs tests, shows coverage report","title":"Home"},{"location":"#timestrap","text":"Time tracking you can host anywhere. Full export support in multiple formats and easily extensible.","title":"Timestrap"},{"location":"#warning","text":"This app is currently very unstable. Everything may, and probably will, change. All migrations are going to be wiped and setup properly before release 1.0 so you will not be able to upgrade to 1.0 from early development.","title":"Warning"},{"location":"#documentation","text":"For more details and screenshots check out our main docs website: https://timestrap.bythewood.me/","title":"Documentation"},{"location":"#superuser-credentials","text":"All installations and the demo create a superuser to get you started, if this is a production deployment you will want to change these. Username: admin Password: admin","title":"Superuser Credentials"},{"location":"#docker-installation","text":"This creates a minimal docker server setup for Timestrap. This currently is in development and may not have persistent data without fiddling. Any help to improve the docker configuration files would be appreciated.","title":"Docker Installation"},{"location":"#docker-requirements","text":"Docker Docker Compose Docker Compose is used for running multiple containers since we require a PostgreSQL database and, not yet but soon, a Redis server for messages and events.","title":"Docker Requirements"},{"location":"#docker-running","text":"Make sure to update the environmental variables in docker-compose.yml and check the timestrap/settings/docker.py file to see if you'd like to change anything then run: sudo docker-compose up --detach To migrate the database, create your first superuser, and create the initial site configuration you then need to run: sudo docker - compose exec web python3 manage . py migrate -- settings = timestrap . settings . docker The Timestrap application should now be running on port 80 of whatever system you ran these commands on, if you ran this locally then that would be http://localhost/ .","title":"Docker Running"},{"location":"#docker-data","text":"All data should be stored in the timestrap_db volume. If you wish to rebuild Timestrap at the latest you can do the following from the timestrap repo you cloned: git pull sudo docker - compose stop sudo docker - compose build sudo docker - compose up -- detach sudo docker - compose exec web python3 manage . py migrate -- settings = timestrap . settings . docker All data will be kept during this process and you'll have the latest version of Timestrap.","title":"Docker Data"},{"location":"#development-installation","text":"If you'd like to contribute code to Timestrap you'll need to do this!","title":"Development Installation"},{"location":"#development-requirements","text":"Python 3.5+ Python Dev Node 8+ pipenv npm Firefox geckodriver Python 3.5+ is required because we use async/await with Channels to support WebSockets and add realtime updates to the client. Python Dev is not required on macOS but if you are on Linux, like Ubuntu, you will need to install it with sudo apt install python3-dev . Node 8+ isn't exactly required, you might be able to get away with an older version and we only use node for building the client. You'll probably need to install pipenv with pip, run pip install pipenv to get this. It's just a better python package manager that allows us to lock our dependencies. Node installs npm by default but you may want to install the latest with npm install --global npm . Firefox is used for functional/selenium tests in conjunction with geckodriver, you can get geckodriver from mozilla's offical releases or you might be able to install it with your systems package manager. Brew on macOS has this with brew install geckodriver . If you have to download it manually make sure to extract it in some sort of bin directory e.g. /usr/local/bin/ .","title":"Development Requirements"},{"location":"#development-setup","text":"Once you have all of the above you can get started! For the global npm install on gulp-cli you may need to run this with sudo depending on how you installed everything above. npm install --global gulp-cli npm install pipenv install --dev After all the dependencies install you can migrate the database and run the server. gulp manage:migrate gulp If you'd like to have some sample data to work with you can run gulp manage:fake after you run gulp manage:migrate . Timestrap should now be running at http://localhost:8000 and gulp + django's test server will automatically recognize and recompile changes to any file allowing for quick modification and review. Once you've made your changes you can test with gulp coverage:development and if that is successful and you want to share your changes create a pull request !","title":"Development Setup"},{"location":"#development-commands","text":"I've prebuilt a variety of build commands for development, you can see a list of them by running gulp --tasks and I will briefly cover some of them here. gulp Will run a webserver with django and build the client with webpack gulp lint Will check all code for style consistency gulp manage:makemigrations Will generate new migrations if models changes gulp manage:migrate Makes sure there is a superuser, runs migrations gulp manage:fake Adds a bunch of fake data for testing gulp manage:reset Resets the database and adds fake data with a superuser gulp coverage:development Lints, runs tests, shows coverage report","title":"Development Commands"},{"location":"configuration/","text":"Configuration \u00b6 Security \u00b6 By default we don't enable TLS/SSL features since this project is often run on an intranet, locally, or in testing environments. If security is a concern of yours, and it should be, you will need to enable TLS/SSL on your reverse proxy and setup a certificate there. For an easy TLS enabled reverse proxy check out Caddy. You will need to configure two settings when you use TLS/SSL on this project. The first is to force TLS/SSL when people visit your site and the second is to make sure that Django REST framework returns corrected URLs behind a reverse proxy. These can be added to timestrap/settings/base.py anywhere: SECURE_SSL_REDIRECT = True SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https') Email \u00b6 Email configuration options are available from the Timestrap admin on a per-site basis. These settings must be supplied to support features such as password reset. To access the settings, navigate to /admin/sites/site/ and select the site to modify. Email Docker \u00b6 You can configure email by setting environmental variables in the docker-compose config for web . These would be: EMAIL_HOST EMAIL_HOST_USER EMAIL_HOST_PASSWORD EMAIL_PORT defaults to port 25 EMAIL_USE_TLS defaults to False , you can set this to True These would go where the SECRET_KEY environmental variable is set Time and Date Localization \u00b6 Language and timezone settings are available on a per-site basis in the site configuration area ( /admin/sites/site/ ). Timestrap uses Moment.js on the frontend so localization will be applied to all dates based on these settings. We'd like to eventually have localization of everything.","title":"Configuration"},{"location":"configuration/#configuration","text":"","title":"Configuration"},{"location":"configuration/#security","text":"By default we don't enable TLS/SSL features since this project is often run on an intranet, locally, or in testing environments. If security is a concern of yours, and it should be, you will need to enable TLS/SSL on your reverse proxy and setup a certificate there. For an easy TLS enabled reverse proxy check out Caddy. You will need to configure two settings when you use TLS/SSL on this project. The first is to force TLS/SSL when people visit your site and the second is to make sure that Django REST framework returns corrected URLs behind a reverse proxy. These can be added to timestrap/settings/base.py anywhere: SECURE_SSL_REDIRECT = True SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')","title":"Security"},{"location":"configuration/#email","text":"Email configuration options are available from the Timestrap admin on a per-site basis. These settings must be supplied to support features such as password reset. To access the settings, navigate to /admin/sites/site/ and select the site to modify.","title":"Email"},{"location":"configuration/#email-docker","text":"You can configure email by setting environmental variables in the docker-compose config for web . These would be: EMAIL_HOST EMAIL_HOST_USER EMAIL_HOST_PASSWORD EMAIL_PORT defaults to port 25 EMAIL_USE_TLS defaults to False , you can set this to True These would go where the SECRET_KEY environmental variable is set","title":"Email Docker"},{"location":"configuration/#time-and-date-localization","text":"Language and timezone settings are available on a per-site basis in the site configuration area ( /admin/sites/site/ ). Timestrap uses Moment.js on the frontend so localization will be applied to all dates based on these settings. We'd like to eventually have localization of everything.","title":"Time and Date Localization"},{"location":"contributing/","text":"Contributing \u00b6 I welcome any and all types of contributions, even if it's just fixing a single small spelling mistake. If you are making code changes I only ask that you do one thing before making a pull request. Make sure that: gulp coverage:development Passes without any issues, if you do a major overhaul of any code I'd also appreciate if you wrote tests for it too! Timestrap is not a project that shoots for 100% test coverage because I consider that a waste of time, I just like to make sure major parts of the code base don't break. (That's not to say I wouldn't like to have 100% test coverage some day...)","title":"Contributing"},{"location":"contributing/#contributing","text":"I welcome any and all types of contributions, even if it's just fixing a single small spelling mistake. If you are making code changes I only ask that you do one thing before making a pull request. Make sure that: gulp coverage:development Passes without any issues, if you do a major overhaul of any code I'd also appreciate if you wrote tests for it too! Timestrap is not a project that shoots for 100% test coverage because I consider that a waste of time, I just like to make sure major parts of the code base don't break. (That's not to say I wouldn't like to have 100% test coverage some day...)","title":"Contributing"},{"location":"docs/","text":"Docs \u00b6 Timestrap's docs are built with mkdocs . If you have dev dependencies installed, pipenv install --dev , then you can use the following commands: gulp docs:serve for testing gulp docs:build to build the files gulp docs:publish to publish to github","title":"Docs"},{"location":"docs/#docs","text":"Timestrap's docs are built with mkdocs . If you have dev dependencies installed, pipenv install --dev , then you can use the following commands: gulp docs:serve for testing gulp docs:build to build the files gulp docs:publish to publish to github","title":"Docs"},{"location":"license/","text":"License \u00b6 The BSD 2-Clause License \u00b6 Copyright (c) 2019 , Isaac Bythewood All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.","title":"License"},{"location":"license/#license","text":"","title":"License"},{"location":"license/#the-bsd-2-clause-license","text":"Copyright (c) 2019 , Isaac Bythewood All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.","title":"The BSD 2-Clause License"},{"location":"permissions/","text":"User Permissions \u00b6 You can edit and add new users on the admin panel at /admin/auth/user/ . You will need to give new users permissions based on the access you wish them to have. If you wish someone be able to see all clients and projects to be able to add them to an entry, but not edit or delete them, you need to give them view permissions under User permissions. These would be core | project | Can view project and core | client | Can view client .","title":"Permissions"},{"location":"permissions/#user-permissions","text":"You can edit and add new users on the admin panel at /admin/auth/user/ . You will need to give new users permissions based on the access you wish them to have. If you wish someone be able to see all clients and projects to be able to add them to an entry, but not edit or delete them, you need to give them view permissions under User permissions. These would be core | project | Can view project and core | client | Can view client .","title":"User Permissions"},{"location":"screenshots/","text":"Screenshots \u00b6 Due to the constant design iterations this is a very incomplete page. There will be more screenshots in the future. You could always try our demo that we mention on the first page of the docs. Timesheet \u00b6 The primary page of Timestrap where you can see all your recent entries.","title":"Screenshots"},{"location":"screenshots/#screenshots","text":"Due to the constant design iterations this is a very incomplete page. There will be more screenshots in the future. You could always try our demo that we mention on the first page of the docs.","title":"Screenshots"},{"location":"screenshots/#timesheet","text":"The primary page of Timestrap where you can see all your recent entries.","title":"Timesheet"},{"location":"sites/","text":"Sites \u00b6 Timestrap takes advantage of Django's \"sites\" framework to support running multiple Timestrap \"sites\" from a single instance of the application. This an optional enhancement, and the base Timestrap application will work fine as a single site without any advanced configuration. Single Site \u00b6 Out of the box, Timestrap is a single site using the fake domain time.strap and name Timestrap . Both the name and the domain name are configurable on the admin. Any domain will fall back to the default site, but it is recommended to at least set the site domain setting be updated to match the actual site domain since emails will use this domain when sending. Multiple Sites \u00b6 Timestrap supports setting up multiple sites with configurations options available on a per-site basis. This functionality may be useful if, for example, there is a need to separate departments or functional teams within a larger group of organization. Sites can be managed by any user with admin access and appropriate permissions: either superuser or the various site and conf permissions. Sites are based on domain and use two primary settings, domain and name in addition to the various configuration options available. Data Sharing \u00b6 All Timestrap data will be related to either one or multiple sites. Clients and Tasks can be related to multiple sites. Entries can be related to a single site. Data with a single-site relationship will automatically be related to the site it was entered on. This settings can be changed from the admin site. Currently, multiple site relationships can only be controlled from the admin site. To use a Client or Task on multiple sites, it must be added to one site and then modified in the admin site to be related to additional sites. Example: Big Project Builders, Inc. \u00b6 Big Project Builders, Inc. (BPB) uses Timestrap to keep track of its progress for various projects & clients. However, with many different teams a single Timestrap instance would have a lot of data and it may come difficulty for individual employees to keep track of progress. So BPB decides to break the instance in to multiple sites - timestrap.bpb.io is the primary instance site, where admin superusers add the Clients and Projects that BPB is working on. design.timestrap.bpb.io is used by BPB's designers to assign and track graphics and design work for projects. development.timestrap.bpb.io is used by BPB's developers to assign and track project development. testing.timestrap.bpb.io is used bu BPB's testing team to record time spent executing and reporting on project tests.","title":"Sites"},{"location":"sites/#sites","text":"Timestrap takes advantage of Django's \"sites\" framework to support running multiple Timestrap \"sites\" from a single instance of the application. This an optional enhancement, and the base Timestrap application will work fine as a single site without any advanced configuration.","title":"Sites"},{"location":"sites/#single-site","text":"Out of the box, Timestrap is a single site using the fake domain time.strap and name Timestrap . Both the name and the domain name are configurable on the admin. Any domain will fall back to the default site, but it is recommended to at least set the site domain setting be updated to match the actual site domain since emails will use this domain when sending.","title":"Single Site"},{"location":"sites/#multiple-sites","text":"Timestrap supports setting up multiple sites with configurations options available on a per-site basis. This functionality may be useful if, for example, there is a need to separate departments or functional teams within a larger group of organization. Sites can be managed by any user with admin access and appropriate permissions: either superuser or the various site and conf permissions. Sites are based on domain and use two primary settings, domain and name in addition to the various configuration options available.","title":"Multiple Sites"},{"location":"sites/#data-sharing","text":"All Timestrap data will be related to either one or multiple sites. Clients and Tasks can be related to multiple sites. Entries can be related to a single site. Data with a single-site relationship will automatically be related to the site it was entered on. This settings can be changed from the admin site. Currently, multiple site relationships can only be controlled from the admin site. To use a Client or Task on multiple sites, it must be added to one site and then modified in the admin site to be related to additional sites.","title":"Data Sharing"},{"location":"sites/#example-big-project-builders-inc","text":"Big Project Builders, Inc. (BPB) uses Timestrap to keep track of its progress for various projects & clients. However, with many different teams a single Timestrap instance would have a lot of data and it may come difficulty for individual employees to keep track of progress. So BPB decides to break the instance in to multiple sites - timestrap.bpb.io is the primary instance site, where admin superusers add the Clients and Projects that BPB is working on. design.timestrap.bpb.io is used by BPB's designers to assign and track graphics and design work for projects. development.timestrap.bpb.io is used by BPB's developers to assign and track project development. testing.timestrap.bpb.io is used bu BPB's testing team to record time spent executing and reporting on project tests.","title":"Example: Big Project Builders, Inc."},{"location":"uses/","text":"Uses \u00b6 The primary use of Timestrap is for a small team to track their hours on a range of projects for multiple clients. This works well for small teams of freelancers and contract workers who have estimates for projects and want try and stay on track for meeting those estimates. Timestrap will allow everyone to track their hours along with providing feedback on how much time/money has been spent on a project thus far. Timestrap is also good at keeping it's users on track with their time spent on a daily basis with a personal overview timesheet showing hours spent in the past five days. If someone is aiming to hit 40 hours of time spent working a week they can, at a glance, see if they need to work more or are on track for their goal. This is very useful for individuals who have flexible work hours. While the primary use is professional time tracking, Timestrap can also be used for personal time tracking if you wish to see what you're spending most of your time on throughout the day.","title":"Uses"},{"location":"uses/#uses","text":"The primary use of Timestrap is for a small team to track their hours on a range of projects for multiple clients. This works well for small teams of freelancers and contract workers who have estimates for projects and want try and stay on track for meeting those estimates. Timestrap will allow everyone to track their hours along with providing feedback on how much time/money has been spent on a project thus far. Timestrap is also good at keeping it's users on track with their time spent on a daily basis with a personal overview timesheet showing hours spent in the past five days. If someone is aiming to hit 40 hours of time spent working a week they can, at a glance, see if they need to work more or are on track for their goal. This is very useful for individuals who have flexible work hours. While the primary use is professional time tracking, Timestrap can also be used for personal time tracking if you wish to see what you're spending most of your time on throughout the day.","title":"Uses"}]}