Caramel-CRM/README.md

# Caramel CRM

**A simple, secure, and GOBD-compliant invoicing and customer management tool for small businesses and freelancers.**

![Caramel CRM Screenshots](./Caramel%20Screenshot.webp)

Caramel CRM is an open-source web application designed for small businesses, freelancers, and non-balancing partnerships (GbRs). It provides an easy-to-use, secure, and GOBD-compliant solution for invoicing and customer management. Since 2025, e-invoicing has become mandatory in Germany, and Caramel CRM aims to bridge the gap for small businesses unprepared for this transition.

- **Self-hosted**: Run it on any web hosting service.
- **GOBD-compliant**: Ensures legal compliance for invoicing.
- **ZUGFeRD/XRechnung/Factur-X support**: Standardized e-invoicing formats.
- **AI-assisted CRM**: Helps with customer care and acquisition.
- **User-friendly**: Designed for non-technical users.


## Status

**Current Status: Prototype**

Caramel CRM is currently in the **prototype phase**. It provides basic invoicing and customer management features but is **not yet GOBD-compliant**. This project has just started development and has applied for the [Prototype Fund](https://www.prototypefund.de/).


## ⚠️ Warning

**Do not use this software in production environments yet!**

- The prototype is **not GOBD-compliant** and lacks essential security audits.
- Data loss or legal non-compliance may occur.
- Use only for **testing and development purposes**.


## Installation

### Prerequisites
- PHP 8.1+
- Composer
- Node.js (for frontend assets)
- SQLite/MySQL/PostgreSQL

### Apache config

```apache
<VirtualHost *:80>
    ServerName crm.tooloop.de
    Redirect permanent / https://crm.tooloop.de/
</VirtualHost>

<VirtualHost *:443>
    ServerName crm.tooloop.de
    DocumentRoot /var/www/html/caramel/public/

    SSLEngine on
    SSLCertificateFile /etc/letsencrypt/live/cloud.tooloop.de/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/cloud.tooloop.de/privkey.pem
    Include /etc/letsencrypt/options-ssl-apache.conf

    <Directory /var/www/html/caramel/public>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/caramel_error.log
    CustomLog ${APACHE_LOG_DIR}/caramel-access.log combined
</VirtualHost>
```

### Steps
1. Clone the repository:
   ```bash
   git clone http://code.tooloop.de/Tooloop/Caramel-CRM.**git**
   cd Caramel-CRM
   ```
2. Create empty database:
   ```bash
   touch database/database.sqlite
   ```
3. Set permissions
   ```bash
   sudo chown -R www-data:www-data /var/www/html/caramel/storage/ bootstrap/cache/
   sudo chmod g+rw  /var/www/html/caramel/storage/ /var/www/html/caramel/bootstrap/cache/
   ```
3. Install dependencies:
   ```bash
   composer update
   composer install
   npm install
   ```
4. Set up the environment:
   ```bash
   cp .env.example .env
   sudo php artisan key\:generate
   ```
5. Create a symbolic link for public storage
   ```bash
   sudo php artisan storage:link
   ```
6. Run migrations and seeders:
   ```bash
   sudo php artisan migrate --seed
   ```
7. Build frontend assets:
   ```bash
   npm run build
   ```
8. Start the development server:
   ```bash
   php artisan serve
   ```

## Configuration

Edit the .env file to configure your database, mail settings, and other environment-specific variables.


### Running the scheduler

Some tasks need to be done in regular interval, e. g. syncing data  with an axternal CalDAV server.  
Therfor the command `artisan schedule:run` should be called every 5 minutes.

You can choose between one of three updating methods by editing the `app.cron_method` value in the database table `settings`:

| Value     | Description                                                                                                                                                |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cron`    | If you can, configure a CRON job in the OS                                                                                                                 |
| `webcron` | Some hosting prividers provide a feature to call a HTTP-request in regular intervals.                                                                      |
| `request` | If both of the above are not possible in your setup, you can choose `request`. The web UI will then regularly call the `/webcron` route from your browser. |


#### Webcron 

Configure a unique token in your `.env`file:

```.environment
...
WEBCRON_SECRET=<YOUR_TOKEN>
...
```
Then make sure this URL is called every 5 minutes:

`http(s)://<YOUR-URL>/webcron?token=<YOUR_TOKEN>`

#### CRON

Add this line in your crontab by typing `crontab -e`:

```bash
*/5 * * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1
```

## Usage

1. Access the application at http://localhost:8000.
2. Log in with the default admin credentials (see .env for details).
3. Start creating invoices and managing customers.

## Contributing

We welcome contributions!

## License
Caramel CRM is open-source software licensed under the [MIT License](LICENCE).

## Contact
For questions or feedback, get in touch :-) 

See all contact information on our wbsite at [Tooloop Multimedia](https://www.tooloop.de).
or find us in the Projekt-Matrix channel: [#caramel-crm:matrix.org](https://matrix.to/#/%23caramel-crm:matrix.org)