## 1. Project Overview & Quickstart (solidtime-io/solidtime) # solidtime - The modern Open-Source TimeTracker [](https://github.com/solidtime-io/solidtime/blob/main/LICENSE.md) [](https://codecov.io/gh/solidtime-io/solidtime) solidtime is a modern open-source time tracking application for Freelancers and Agencies. ## Features - Time tracking: Track your time with a modern and easy-to-use interface - Projects: Create and manage projects and assign project members - Tasks: Create and manage tasks and assign tasks to projects - Clients: Create and manage clients and assign clients to projects - Billable rates: Set billable rates for projects, project members, organization members and organizations - Multiple organizations: Create and manage multiple organizations with one account - Roles and permissions: Create and manage organizations - Import: Import your time tracking data from other time tracking applications (Supported: Toggl, Clockify, Timeentry CSV) ## Self Hosting If you are looking into self-hosting solidtime, you can find the guides [here](https://docs.solidtime.io/self-hosting/intro) We also have an examples repository [here](https://github.com/solidtime-io/self-hosting-examples) If you do not want to self-host solidtime or try it out you can sign up for [solidtime cloud](https://www.solidtime.io/) ## Issues & Feature Requests If you find any **bugs in solidtime**, please feel free to [**open an issue**](https://github.com/solidtime-io/solidtime/issues/new) in this repository, with instructions on how to reproduce the bug. If you have a **feature request**, please [**create a discussion**](https://github.com/solidtime-io/solidtime/discussions/new?category=feature-requests) in this repository. ## Contributing Please open an issue or start a discussion and wait for approval before submitting a pull request. This does not apply to tiny fixes or changes however, please keep in mind that we might not merge PRs for various reasons. **If you submit an AI slop pull request (especially without following the proper procedure), you will be banned from future contributions to solidtime.** To keep that manageable, pull requests from authors who are not vouched are closed automatically, unless they change 50 lines or fewer. To get vouched, open an issue or discussion first and explain how you intend to implement the change. Once we have agreed on the approach, we vouch for you. See [Vouched contributors](./CONTRIBUTING.md#vouched-contributors). Please read the [CONTRIBUTING.md](./CONTRIBUTING.md) before sumbitting a Pull Request. We do accept contributions in the [documentation repository](https://github.com/solidtime-io/docs) f.e. to add new self-hosting guides. ## Security Looking to report a vulnerability? Please refer our [SECURITY.md](./SECURITY.md) file. ## License This project is open-source and available under the GNU Affero General Public License v3.0 (AGPL v3). Please see the [license file](LICENSE.md) for more information. ## 2. Official Technical Reference & Guides (solidtime-io/docs) ## File: README.md # solidtime | Documentation solidtime is a modern open-source time tracking application for freelancers and agencies. This repository contains the documentation for solidtime. The documentation is built using [Docusaurus](https://docusaurus.io/). ## Installation First, clone the repository: ```bash git clone git@github.com:solidtime-io/docs.git ``` Then, install the dependencies: ```bash npm install ``` ### Local Development ```bash npm run start ``` This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. Some features, like search and the API page, won't work in the local development environment. If you want to test this, you need to build the documentation and serve from the `build` directory. ### Build ```bash npm run build ``` This command generates static content into the build directory. You can test the build by running a local HTTP server: ```bash npm run serve ``` ## Contributing Contributions to the documentation are welcome. ## License The documentation is licensed under the MIT License. See [LICENSE](LICENSE.md) for more information. --- ## File: docs/user-guide/access-api.md --- sidebar_position: 8 --- # API access The solidtime API is a RESTful API that allows you to access and manipulate data in solidtime. The API is designed to be easy to use and to provide all the functionality that is available in the solidtime web application. ## Creating an API Token To access the API, you need an API token. You can create an API token in the user settings. 1. Click on "Profile Settings" in the bottom left corner 2. Scroll down to the "Create API Token" section 3. Enter a name and click on "Create API Token" 4. The API token will be displayed in a popup. Copy the token and store it in a safe place. :::warning The API token is only displayed once. If you lose the token, you need to create a new one. ::: ## Using the API The API token is a JWT token. You need to add the token to the Authorization header of your HTTP requests with a `Bearer ` prefix. **Example:** ``` Authorization: Bearer ``` All API endpoints are documented in [the API reference](/api-reference). --- ## File: docs/user-guide/billable-rates.md --- sidebar_position: 5 --- # Billable rates Billable rates is a price per hour for time tracked in solidtime. Billable rates can be set on multiple levels: 1. **Project member** - for a specific user in a specific project 2. **Project** - for all users in a specific project 3. **Organization member** - for a specific user in the organization 4. **Organization** - for all users Setting the billable rate is optional on all levels. The billable rate on a level overwrites the billable rate of the level above. (Level 1 overwrites level 2, level 2 overwrites level 3, etc.) **Example 1:** A user called Bob is a member of the organization and tracks 3 hours on a project called "Project A". - Organization billable rate: 50€ - Project billable rate: 60€ - Bob's billable rate in "Project A": 70€ Bob's tracked time in "Project A" will be billed with 70€ per hour. **Example 2:** A user called Alice is a member of the organization and tracks 3 hours on a project called "Project B". - Organization billable rate: 50€ - Alice's billable rate in the organization: 70€ - Project billable rate: 60€ - Alice's billable rate in "Project B": not set Alice's tracked time in "Project B" will be billed with the projects billable rate 60€ per hour, since she does not have a billable rate set on her own in the project. ## How to set billable rates In the following sections, you will learn how to set billable rates on different levels. In general, the process is the same for all levels. Before you update a billable rate, you will be asked to confirm that the new billable rate will be applied to all affected existing time entries. If you cancel, the billable rate will not be saved. When the billable rate is updated, only the time entries that use the specific billable rate will be updated. If a time entry has a billable rate set on a higher level, the time entry will not be updated. **Example:** Bob and Alice are members of the organization "Great company". Bob tracks 3 hours on "Project A". The billable rate for Bob in "Project A" is 100€. Alice tracks 4 hours without a project. The administrator of the organization now sets the billable rate for the organization to 50€ and confirms the update. This will update Alice's time entries to 50€ per hour, but Bob's time entries will stay at 100€ per hour, since the project billable rate has a higher priority. :::note If you want to preserve a billable rate for certain time entries, you can do so by setting a project billable rate and moving the time entries to that project. ::: ### Organization billable rate 1. Go to the Settings tab in the navigation on the left 2. Scroll down to the "Billable Rate" section and set the billable rate 3. When you click on "Save" a popup will appear asking you to confirm that the new billable rate will be applied to existing time entries ### Organization member billable rate 1. Go to the "Members" tab in the navigation on the left 2. Find the user you want to set the billable rate for and click on the three dots on the right side of the user 3. Click on "Edit" 4. Under "Billable" select "Custom rate" and set the billable rate 5. When you click "Update" a popup will appear asking you to confirm that the new billable rate will be applied to existing time entries. ### Project billable rate 1. Go to the "Projects" tab in the navigation on the left 2. Find the project you want to set the billable rate for and click on the three dots on the right side of the project 3. Click on "Edit" 4. Under "Billable Default" select "Custom rate" and set the billable rate 5. When you click "Update" a popup will appear asking you to confirm that the new billable rate will be applied to existing time entries. It is also possible to set the billable rate when creating a new project. ### Project member billable rate 1. Go to the "Projects" tab in the navigation on the left 2. Click on the project you want to set the billable rate for to open the project 3. Under "Project members" find the user you want to set the billable rate for and click on the three dots on the right side of the user and click on "Edit" 4. Set the billable rate in the "Billable rate" field 5. When you click "Update project member" a popup will appear asking you to confirm that the new billable rate will be applied to existing time entries. If the user is not a member of the project yet, you can add the user to the project with the "+ Add Member" button and set the billable rate at the same time. --- ## File: docs/user-guide/billing.md # Billing (solidtime Cloud) You can manage your subscription of solidtime Cloud in the Billig dashboard. The billing dashboard can be accessed through the "Billing" entry in the left navigation. ## Adding a VAT number After choosing your plan and clicking on "Subscribe" you need to click "Continue". In the next step click on "Add VAT number" before adding your payment information. Now you need to enter your VAT number and the address of your business. Afterwards scroll down and click on "Add VAT number". Now the price should update to the price without VAT. You can continue the payment process to finalize the purchase of solidtime Cloud. --- ## File: docs/user-guide/breaks.md --- sidebar_position: 4 --- # Breaks Breaks let you track **[pauses between your work time entries](#misaligned-breaks)**. Unlike work time entries, breaks have no project, tags, or billable status. Break time is **counted separately from work time** everywhere: dashboard statistics only count work time, day totals show breaks separately, and reports can include or exclude them. ## Enabling breaks Break tracking is **disabled by default**. An owner or admin can enable it in the organization settings: 1. Open the organization switcher in the top-left corner. 2. Go to **Organization Settings**. 3. Check **Allow tracking breaks** and click **Save**. Once enabled, break controls appear in the time tracker, the timesheet gets a dedicated Break row, and the calendar and reporting pick up breaks as well. ## Taking a break from the timer ### Take a break While a timer is running, a coffee-cup **Take a break** button appears next to the stop button. Clicking it stops the current work entry and immediately starts a break entry, so no time is lost between the two. ### Resume work While the break is running, the tracker shows an **On break** state. One click on **Resume** ends the break and starts a new work entry with the interrupted entry's description, project, and other details restored, so getting back to work is a single click. You can also end the break with the regular stop button if you don't want to resume the previous work right away. ### Start a break without a running timer A break doesn't have to start from a running timer: **Start Break** in the tracker's options menu starts a break while no timer is running, for example when you stopped the timer but actually wanted to take a break. ## Breaks on the Time page Break entries appear alongside your other entries, marked with a coffee-cup **Break** label. The day header shows the day's break time separately from the work total, so a day reads like _30min break · 5h 00min_. A break that sits far away from your work entries is flagged with a warning sign, see [Misaligned breaks](#misaligned-breaks). ## Breaks in the timesheet With breaks enabled, the [timesheet](./timesheet.md) always shows a pinned **Break** row at the bottom of the grid. Enter a duration into a break cell just like any other cell. **Copy last week** copies break entries along with everything else. Because a break should [sit between work entries](#misaligned-breaks), the timesheet places it for you: 1. It automatically looks for a free gap between that day's work entries where the break stays within 30 minutes of work on both sides, and centers the break there. 2. When no such gap exists, the break is placed in any gap big enough to hold it, directly after the work entry before it. 3. When no gap can hold the break at all, a placement dialog opens to let you place the break manually. ### Manually placing breaks The placement dialog shows the suggested position and lets you adjust the break's time before anything is saved: - With a **single work entry** on the day, the dialog splits it in two and puts the break in between. You can adjust the break's time; it must lie inside the work entry, leaving at least a minute of work on each side. - With **several work entries**, the dialog shifts the surrounding entries just enough to open a slot, and shows exactly which entries move before you confirm. If the chosen time would leave the break [misaligned](#misaligned-breaks), the dialog warns you up front. ## Breaks in the calendar In the calendar, right-click a free spot and choose **Add Break** to create a break at that time. When you right-click in a gap between two time entries, the suggested break is prefilled to fill the space between them exactly. Break entries are drawn with a hatched texture so they can't be confused with a project color, and [misaligned breaks](#misaligned-breaks) carry a warning sign. The day headers show the day's break time next to the work total. Otherwise breaks behave like any entry: drag to move, resize to adjust, right-click to edit, duplicate, split, or delete. ## Misaligned breaks A break records a pause between work, so solidtime expects every break to sit directly between work entries. A break counts as **misaligned** when it is more than **30 minutes** away from the nearest work entry on either side, or when one side has no work at all. This is a hint, not an error: nothing is blocked and the break is saved either way. The check helps you spot breaks that drifted away from your work, for example after editing or deleting the entries around them. It is recalculated from your current entries, so correcting the times clears the flag on its own. Every page points misaligned breaks out with an amber warning sign. On the **Time page** it appears next to the break entry, and clicking it opens a shortcut that jumps to the break's day in the calendar, where it is easiest to fix (shown above). **Timesheet**: the sign appears in the header of the affected day **Calendar**: the break entry itself carries the sign ## Editing breaks Every time entry has a type, either **Work time** or **Break**, which you can change in the entry's edit dialog. Note that switching an entry to Break clears its project, task, tags, and billable status, since breaks can't carry any of these. When you select multiple entries and use mass update, break entries are **skipped entirely** if the change involves a project, tags, or billable status. A warning in the dialog and a notice after saving tell you which entries were left untouched. ## Disabling breaks again Turning **Allow tracking breaks** off doesn't delete anything: existing break entries stay visible on the Time page, in the timesheet (as a read-only Break row), and in the calendar. You just can't create new ones. The break controls disappear, and **Copy last week** leaves last week's breaks out. The reporting pages are an exception: while breaks are disabled, reports only include work time, so existing break entries are hidden there. Enable breaks again to see them in reports. ## Permissions Tracking breaks works like tracking any other time entry: every role that can track time can track breaks. Only **owners** and **admins** can change the **Allow tracking breaks** organization setting. See [Roles](./roles.md) for a full overview of role-based permissions. --- ## File: docs/user-guide/delete-users-organizations.md --- sidebar_position: 9 --- # Delete organizations or your account ## Delete a organization To delete an organization, you need to be the owner of the organization. If you are the owner, you can delete the organization in the organization settings. 1. Click on "Settings" in the left navigation 2. Scroll down to the "Delete Organization" section After you clicked on the "Delete Organization" button, you will be asked to confirm the deletion. The deletion of an organization is irreversible and all data will be lost. The users of the organization will not be deleted. If the users are not part of another organization, a new empty personal organization will be created for them. ## Delete your account 1. Click on "Profile Settings" in the left navigation 2. Scroll down to the "Delete Account" section After you clicked on the "Delete Account" button, you will be asked to confirm the deletion. The deletion of a user is irreversible and all data will be lost. If the user is part of an organization, but NOT the owner, the user will be converted to a placeholder user in the organization, so that the time entries of the user are not lost. If the user is owner of an organization, the organization will automatically be deleted during the account deletion, but only if the organization has no other members. If the organization has other members, the deletion will be prevented. To delete your account in this case, you need to transfer the ownership to another user or delete the organization first and then delete your account. --- ## File: docs/user-guide/export.md --- sidebar_position: 7 --- # Export To make sure that you can always access your data, we provide a way to export your data from solidtime. The export can also be useful to migrate from a self-hosted solidtime instance to the cloud version or to another self-hosted instance. ## Exporting an organization 1. Choose the organization you want to export in dropdown in the left top corner 2. Click on "Export" in the left navigation under "Admin" (You need to be Admin or Owner of the organization to see this) 3. Click on "Export" and save the ZIP file The ZIP file contains the following data: - Clients - Members - Organization invitations - Organization settings - Projects (incl. members) - Tags - Tasks - Time entries ### Technical details The export is a ZIP file that contains a CSV file for each entity. It also contains a `meta.json` file that contains the metadata of the export. The CSV files are: - `clients.csv` - `members.csv` - `organization_invitations.csv` - `organizations.csv` - `project_members.csv` - `projects.csv` - `tags.csv` - `tasks.csv` - `time_entries.csv` The CSV files are named after the entity in the database. The columns in the CSV files are named after the attributes of the entity. The CSV files are UTF-8 encoded, have a header row, and are separated by a comma (`,`). If necessary the values are enclosed by double quotes (`"`). More information about how data types are exported: - Boolean: `true` or `false` - Date time: ISO 8601 format, Timezone is always UTC (example: `2021-01-01T12:00:00Z`) - IDs: UUID version 4 (example: `ebf1384d-6dc7-4f93-872d-2f53dd481d30`) - Null values: Empty string (`""`) - Money values: Integer value in cents (example: `1000` for `10.00`) The `meta.json` file contains the following data: - `id`: The ID of the export - `version`: The version of the export format - `organizations`: An array of organization keys that are exported - `exported_at`: The timestamp when the export was created in ISO 8601 format (example: `2021-01-01T12:00:00Z`) --- ## File: docs/user-guide/import.md --- sidebar_position: 6 --- # Import To make migrating to solidtime as easy as possible, we provide a way to import your existing data into solidtime. Currently, we support importing data from the following sources: - [Toggl](https://toggl.com/) - [Clockify](https://clockify.me/) - [Harvest](https://www.getharvest.com/) - solidtime - [Generic CSV Import](#generic-csv-import) More import sources will be added in the future. If you are using a different time tracking tool and would like to import your data into solidtime, please [contact us](mailto:hello@solidtime.io) or [create a GitHub issue](https://github.com/solidtime-io/solidtime/issues/new). ## How to import data To import data into solidtime, follow these steps: 1. Select the organization you want to import the data to in the left top corner 2. Click on "Import" in the left navigation under "Admin" (You need to be Admin or Owner of the organization to see this) 3. Select the import that you want to use 4. After selecting the import an instruction will be shown on how to export the data from the source tool 5. Follow the instruction and upload the exported file in the upload area below the instructions 6. Click on "Import Data" Depending on the amount of data that you are importing, the import can take a few minutes. After the import is finished, a modal will be shown with the result of the import. **Why are there multiple import types for the same data source? (f.e. Toggl Time Entries & Toggl Data Importer)** Many time tracking tools don't provide one export file that contains all the data. Therefore, we provide multiple import types for the same data source, so you can import the data in multiple steps. To get the most accurate data, the order of the imports is important. For example, when importing Toggl data, you should first use the "Toggl Data Importer" and then the "Toggl Time Entries" import. The correct order of the imports is shown in the instructions after selecting the import. Please read those instructions carefully, before importing data. ## Generic CSV Import solidtime offers to import from common other time tracking tools, but you might want to migrate from a different tool or a custom solution like an Excel sheet. In that case the generic CSV import might help you achieve that. To use this import method you need to convert your data into CSVs with a data structure like the one defined in the following sections. Since the time entries importer can indirectly also import projects it is better to first import the projects and then the time entries. This way you can import more information about the project then just the name. All generic import CSVs need to be comma-seperated and in UTF-8. If necessary the values can be enclosed in `"`. ### Generic projects importer | Column | Description | Data type | |------------------|-------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------| | name | Name of the project | Text (f.e. `Big project 2030`) | | color | Color of the project. If empty a random color that matches the style of solidtime will be used. | Color in Hex (f.e. `#ef5350`) | | billable_rate | Billable rate for this project (in Cents) | Number (f.e. `20000`) | | is_public | Whether the project is public | `true` or `false` | | client | The name of the client of the project. If empty the project doesn't have a client | Text (f.e. `Big ACME company`) | | billable_default | Whether the time entries should be billable per default | `true` or `false` | | estimated_time | Estimated time the project takes (in seconds) | Number (f.e. `3600`) | | archived_at | When the project was archived. If empty the project is not archived | ISO 8601 format, Timezone is always UTC (example: `2021-01-01T12:00:00Z`) | ### Generic time entries importer | Column | Description | Data type | |-------------|------------------------------------|----------------------------------------------------------------------------------------| | description | Name of the project | Text (f.e. `Video conference about XY`) | | billable | Whether the time entry is billable | `true` or `false` | | client | Name of the client | Text (f.e. `Big company`) | | project | Name of the project | Text (f.e. `Big project 2030`) | | tags | List of tags | Comma-seperated list (f.e. `Project managment,Meeting`) | | start | Start timestamp | Date time in ISO 8601 format, Timezone is always UTC (example: `2021-01-01T12:00:00Z`) | | end | End timestamp | Date time in ISO 8601 format, Timezone is always UTC (example: `2021-01-01T12:10:01Z`) | | task | Name of the task | Text (f.e. `Feature YX`) | | user_name | Name of the user | Text (f.e. `Peter Tester`) | | user_email | Email of the user | Email (f.e. `peter.tester@big-agency.test`) | --- ## File: docs/user-guide/intro.md --- slug: / sidebar_position: 1 --- # Introduction Welcome to the User-Guide section of the solidtime documentation! This guide is for users of solidtime who want to learn how to use the application. --- ## File: docs/user-guide/roles.md --- sidebar_position: 2 --- # Roles In organizations with multiple users it is important to have different roles to manage the access and permissions of the users. The following roles are available in solidtime: ## Owner The owner has full access of the organization. The owner is the only role that can: - delete the organization - transfer the ownership to another user - solidtime Cloud: access to the billing settings ## Admin The admin has full access to the organization, except for the stuff that only the owner can do. ## Manager The manager has full access to projects, clients, tags, time entries, and reports, but can not manage the organization or the users. ## Employee An employee is a user that is only using the application to track time, but has no administrative rights. ## Placeholder Placeholder users are special users that can not do anything in the organization. If you use solidtime cloud, those users are not billed. Placeholder users are used for imports and to remove users from the organization without deleting their time entries. **Import** If you are importing data from another time tracking tool, the importer, depending on the data, needs to create users in the organization. Since you might want to invite users to solidtime one by one, the importer only creates placeholder users, that will be used for their time entries. **Deactivate members** If you want to remove a user from the organization, but you don't want to delete their time entries, you can deactivate the member from the organization and the user will be converted to a placeholder user. If you use solidtime Cloud, those deactivated members are also not billed. ### Invite placeholder users to become real users If you want to invite a placeholder user to become a real user in the organization, you can do this by following these steps: 1. Go to the "Members" tab in the navigation on the left 2. Find the placeholder user you want to invite and click on the "Invite" button on the right side of the user