Skip to content

Latest commit

 

History

History
186 lines (129 loc) · 8.01 KB

readme.md

File metadata and controls

186 lines (129 loc) · 8.01 KB
Raw


Saaster is a CFML-based framework designed to simplify the development of SaaS applications. It is built on a modern stack, using Lucee 6, NGINX, and MySQL 8.1, and is fully containerized with Docker Compose. The architecture provides a solid foundation for building scalable SaaS platforms while keeping configuration flexible. Saaster includes core features such as user authentication, API integration, and a modular approach to extend functionality. This framework allows developers to focus on building their application's unique components without reinventing common SaaS patterns.

🌐 Website
📚 Documentation
📃 License

Branches

Saaster is organized into three primary branches to support different stages of development and deployment:

  • Development: This is the default branch where new features, bug fixes, and improvements are implemented. Developers work primarily in this branch. It may contain unstable code, and its purpose is for active development and experimentation. Use this branch for contributing and testing new functionality.
  • Staging: The staging branch is used to test features that have been merged from development. It mimics the production environment as closely as possible to ensure stability before release. The staging branch uses a copy of the production database for testing with live data, making it suitable for integration and acceptance testing.
  • Production: The production branch contains the stable version of Saaster that is deployed to the live environment. Code is only merged into production after thorough testing in staging. This branch should always reflect the current state of the live environment and should be free from experimental or incomplete features.



Development Setup

To set up Saaster for local development, follow these steps. This will allow you to work on the project, make modifications, and test it in a development environment. Make sure Docker is installed and running before you begin.

Step-by-step setup:

1. Open a terminal and navigate to the desired folder
Choose the directory where you want to clone the project.

cd /path/to/your/folder

2. Clone the Saaster repository

git clone https://github.com/PAWECOGmbH/saaster

3. Navigate to the project folder

cd saaster

4. Configure environment variables
Copy the example environment file and modify the settings to match your local setup:

mv config/example_dev.env .env

Update the .env file with your configuration. You can also adopt the suggestions for the local environment.

5. Set up the application configuration
Copy the example configuration file and make any necessary changes:

mv config/example.config_dev.cfm www/config.cfm

Edit www/config.cfm to suit your development environment.


6. Start the containers
Use Docker Compose to start the development environment:

docker compose -f compose-dev.yml up

7. Configure Lucee
Access the Lucee admin interface:

  • URL: http://localhost:8080/lucee/admin/server.cfm
  • Steps:
    • Set up the database connection.
    • Configure SMTP (you can use Inbucket for local email handling).
    • Adjust any additional settings required for your development setup.

8. Set up Saaster
Run the setup script to initialize Saaster:

  • URL: http://localhost:8080/setup/index.cfm
  • Work your way through the wizard.
  • Complete the registration; the first registration creates the Sysadmin account.
  • Access Inbucket (local email client) at http://localhost:9000 to view any emails.



Optional: Load Test Data

If you want to load test data into your database:

  1. In the folder config/db/dev/, you'll find several SQL files containing test data. For example, to import the "create-plans.sql" file:
cat ./config/db/dev/create-plans.sql | docker exec -i {MYSQL_CONTAINER_NAME} mysql -u {MYSQL_USER} -p{MYSQL_PASSWORD} {MYSQL_DATABASE}

Replace the following placeholders:

  • {MYSQL_CONTAINER_NAME}: The name of your MySQL container.
  • {MYSQL_USER}: Your MySQL user.
  • {MYSQL_PASSWORD}: Your MySQL password (ensure no space after -p).
  • {MYSQL_DATABASE}: Your MySQL database name.
  1. You can also import mock customers and invoices:
  • URL: http://localhost:8080/setup/mockdata/index.cfm



Preserve Configurations with a Custom Docker Image

After configuring Lucee and Saaster, you may want to create a custom Docker image to preserve your settings:

  1. Stop the Lucee container:
    docker stop <lucee_container_name>

  2. Commit the container to create an image:
    docker commit <lucee_container_name> <your_image_name>:version
    Example: docker commit lucee_container saaster:20241002

  3. Remove the old container:
    docker container rm <lucee_container_name>

  4. Update your .env file with the new image name:
    LUCEE_IMAGE=saaster:20241002

  5. Restart the container with your saved image:
    docker compose -f compose-dev.yml up -d



Live Setup

For production deployment, Saaster can be run on an Ubuntu server using Docker. This setup ensures a stable and scalable environment. A detailed guide on how to configure the server, set up Docker, and deploy Saaster in a live environment can be found in the official documentation:

  • Production Setup Guide: coming soon



Contributing

We welcome contributions from developers to help improve Saaster. Whether it's fixing bugs, adding new features, or improving documentation, contributions are highly appreciated. Follow the steps below to get started:

  1. Fork the repository
    First, fork the Saaster repository to your GitHub account.

  2. Clone your fork
    Clone your forked repository to your local machine:
    git clone https://github.com/{your-username}/saaster
    cd saaster

  3. Create a new branch
    Always create a new branch for your changes to keep things organized:
    git checkout -b feature/your-feature-name

  4. Make your changes
    Implement your changes and commit them with a clear and concise commit message:
    git add .
    git commit -m "Add feature description"

  5. Push your branch
    Push your branch to your forked repository:
    git push origin feature/your-feature-name

  6. Create a pull request
    Go to the Saaster repository on GitHub and create a pull request from your forked repository. Ensure your pull request clearly describes the changes and why they are necessary.

Guidelines

  • Code style: Follow the existing code style of the project.
  • Testing: Ensure that your changes do not break any existing functionality. Add tests where applicable.
  • Documentation: If your changes affect functionality, please update the relevant documentation.

For more information or if you're unsure about something, feel free to open an issue or ask for guidance on an existing one.



Dependencies