Time tracking you can host anywhere, built on Django. Full export support in multiple formats and easily extensible.
djangodockerhandcodedpythonself-hostedtime-trackingtimetracker
1# Timestrap
2
3[](https://github.com/overshard/timestrap/blob/master/LICENSE.md)
4
5Time tracking you can host anywhere. Full export support in
6multiple formats and easily extensible.
7
8
9## Warning
10
11This app is currently very unstable. Everything may, and probably will, change.
12All migrations are going to be wiped and setup properly before release 1.0 so
13you will not be able to upgrade to 1.0 from early development.
14
15
16## Documentation
17
18For more details and screenshots check out our main docs website:
19[https://timestrap.bythewood.me/](https://timestrap.bythewood.me/)
20
21
22## Superuser Credentials
23
24All installations and the demo create a superuser to get you started, if this
25is a production deployment you will want to change these.
26
27- Username: `admin`
28- Password: `admin`
29
30
31## Docker Installation
32
33This creates a minimal docker server setup for Timestrap. This currently is
34in development and may not have persistent data without fiddling. Any help to
35improve the docker configuration files would be appreciated.
36
37### Docker Requirements
38
39- Docker
40- Docker Compose
41
42Docker Compose is used for running multiple containers since we require a
43PostgreSQL database and, not yet but soon, a Redis server for messages and
44events.
45
46### Docker Running
47
48Make sure to update the environmental variables in `docker-compose.yml` and
49check the `timestrap/settings/docker.py` file to see if you'd like to change
50anything then run:
51
52 sudo docker-compose up --detach
53
54To migrate the database, create your first superuser, and create the initial
55site configuration you then need to run:
56
57 sudo docker-compose exec web python3 manage.py migrate --settings=timestrap.settings.docker
58
59The Timestrap application should now be running on port 80 of whatever system
60you ran these commands on, if you ran this locally then that would be
61[http://localhost/](http://localhost/).
62
63### Docker Data
64
65All data should be stored in the timestrap_db volume. If you wish to rebuild
66Timestrap at the latest you can do the following from the timestrap repo you
67cloned:
68
69 git pull
70 sudo docker-compose stop
71 sudo docker-compose build
72 sudo docker-compose up --detach
73 sudo docker-compose exec web python3 manage.py migrate --settings=timestrap.settings.docker
74
75All data will be kept during this process and you'll have the latest version
76of Timestrap.
77
78## Development Installation
79
80If you'd like to contribute code to Timestrap you'll need to do this!
81
82### Development Requirements
83
84- Python 3.5+
85- Python Dev
86- Node 8+
87- pipenv
88- npm
89- Firefox
90- geckodriver
91
92Python 3.5+ is required because we use async/await with Channels to support
93WebSockets and add realtime updates to the client. Python Dev is not required
94on macOS but if you are on Linux, like Ubuntu, you will need to install it with
95`sudo apt install python3-dev`.
96
97Node 8+ isn't exactly required, you might be able to get away with an older
98version and we only use node for building the client.
99
100You'll probably need to install pipenv with pip, run `pip install pipenv` to
101get this. It's just a better python package manager that allows us to lock our
102dependencies.
103
104Node installs npm by default but you may want to install the latest with
105`npm install --global npm`.
106
107Firefox is used for functional/selenium tests in conjunction with geckodriver,
108you can get geckodriver from [mozilla's offical releases](https://github.com/mozilla/geckodriver/releases)
109or you might be able to install it with your systems package manager. Brew on
110macOS has this with `brew install geckodriver`. If you have to download it
111manually make sure to extract it in some sort of `bin` directory e.g.
112`/usr/local/bin/`.
113
114### Development Setup
115
116Once you have all of the above you can get started! For the global npm install
117on gulp-cli you may need to run this with sudo depending on how you installed
118everything above.
119
120 npm install --global gulp-cli
121 npm install
122 pipenv install --dev
123
124After all the dependencies install you can migrate the database and run the
125server.
126
127 gulp manage:migrate
128 gulp
129
130If you'd like to have some sample data to work with you can run
131`gulp manage:fake` after you run `gulp manage:migrate`.
132
133Timestrap should now be running at [http://localhost:8000](http://localhost:8000)
134and gulp + django's test server will automatically recognize and recompile
135changes to any file allowing for quick modification and review.
136
137Once you've made your changes you can test with `gulp coverage:development` and
138if that is successful and you want to share your changes create a
139[pull request](https://github.com/overshard/timestrap/pulls)!
140
141### Development Commands
142
143I've prebuilt a variety of build commands for development, you can see a list
144of them by running `gulp --tasks` and I will briefly cover some of them here.
145
146- `gulp` Will run a webserver with django and build the client with webpack
147- `gulp lint` Will check all code for style consistency
148- `gulp manage:makemigrations` Will generate new migrations if models changes
149- `gulp manage:migrate` Makes sure there is a superuser, runs migrations
150- `gulp manage:fake` Adds a bunch of fake data for testing
151- `gulp manage:reset` Resets the database and adds fake data with a superuser
152- `gulp coverage:development` Lints, runs tests, shows coverage report