Metadata-Version: 2.4
Name: lampsible
Version: 2.6.0
Summary: Deploy and set up LAMP stacks with Ansible
Author-email: Belal Ibrahim <belal.ibrahim@proton.me>
Project-URL: Homepage, https://github.com/belal-i/lampsible
Project-URL: Issues, https://github.com/belal-i/lampsible/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Framework :: Ansible
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ansible-core>=2.15.13
Requires-Dist: ansible-runner>=2.4.1
Requires-Dist: requests>=2.32.3
Requires-Dist: fqdn>=1.5.1
Dynamic: license-file

# Lampsible

## About

Complete LAMP stack setup, with a single CLI command. Powered by Ansible under the hood.
This tool can automate almost anything that you'd expect from a LAMP stack.

### Features

* Production ready web apps, powered by LAMP stacks, in a single command
* SSL certificates via Certbot / Let's Encrypt
* Most common CMS applications are supported:
  * WordPress, including custom themes and plugins
  * Joomla
  * Drupal
  * TYPO3
* Custom Laravel apps
* Fresh, out-of-the-box LAMP stacks
* Custom Apache configuration (custom webroot, vhosts, etc.)
* Apache or MySQL by itself
* SSL via test certificates / self signed, ideal for test environments
* Custom PHP extensions, php.ini settings, phpMyAdmin, Composer packages, etc.
* Misc. apps: SuiteCRM
* And so on...


## Requirements

* Local host: Unix system with Python 3.9 or newer. Tested on Ubuntu Linux, Gentoo Linux and Linux Mint.
  Might work on macOS, but I haven't tested that. Won't work on Windows,
  because Ansible requires a Unix like system.
* Remote server: Ubuntu >= 20, <= 24. You need SSH access and root privilege.
* (Optional): Lampsible is designed so that you run it in your local CLI, and it installs a web app
  on your remote server. However, you can also run it locally. This is useful if you want to install
  a local test server. In that case, your local machine should be similar as the "remote server"
  outlined above, ie. Ubuntu Linux.

## Installing

### Pip

```
pip install lampsible
```

### Alternative: from source

```
git clone https://github.com/belal-i/lampsible
cd lampsible
python3 -m pip install .
```

## Usage

There are 2 ways to use Lampsible: as a CLI tool, or as a Python library.

### CLI tool

Once you've installed Lampsible onto your local environment, you can run the `lampsible` command.

It takes the format: `lampsible user@host ACTION [OPTIONS]`

If you are running locally, you can simply do: `lampsible localhost ACTION [OPTIONS]`

It is designed to be very simple to use. If you omit some important parameter,
like admin user, password, site title, etc, you will be prompted to enter a value,
or fall back to a default.

Below are some examples:

* Install a production ready WordPress site:
  ```
  lampsible someuser@somehost.com wordpress \
      --email-for-ssl you@yourdomain.com
  ```

* Install a production ready WooCommerce shop
  with some other plugins and a custom theme:
  ```
  lampsible someuser@somehost.com wordpress \
      --email-for-ssl you@yourdomain.com \
      --wordpress-plugins woocommerce,wordpress-seo,akismet,wordfence \
      --wordpress-theme frutiger-aero
  ```

* Install a production ready Joomla site:
  ```
  lampsible someuser@somehost.com joomla \
      --email-for-ssl you@yourdomain.com
  ```

* Install Drupal on a test server. Certbot will set up a
  test certificate. Also, Apache and MySQL will run on two separate hosts.
  ```
  lampsible someuser@somehost.com drupal \
      --database-system-user-host otheruser@dbserver.somehost.com \
      --database-host 10.0.1.2 \
      --database-username dbuser
      --ssl-test-cert \
      --apache-server-admin you@yourdomain.com \
  ```

* Set up a LAMP stack with various custom configuration and a self signed SSL certificate on some local VM:
  ```
  lampsible someuser@192.168.123.123 lamp-stack \
      --ask-remote-sudo \
      --ssl-selfsigned \
      --database-username dbuser \
      --database-name testdb \
      --apache-vhost-name some-legacy-app \
      --apache-document-root /var/www/html/some-legacy-app/some-dir/public \
      --php-extensions mysql,xml,mbstring,xdebug,gd
  ```

Run `lampsible --help` for a full list of options.

### Python library

Lampsible can be used as a Python library, so if you want to build your own tool,
and want to leverage Lampsible's features to automate various Apache webserver setups,
you can do that.

It could look something like this:

```python
# my_automation_tool.py

from lampsible.lampsible import Lampsible

# Simple WordPress setup
lampsible = Lampsible(
    web_user='someuser',
    web_host='somehost.example.com',
    action='wordpress',
    # Required for Certbot. You can also use email_for_ssl
    apache_server_admin='someuser@example.com',
    database_name='wordpress',
    database_username='db-user',
    database_password='topsecret',
    admin_username='your-wordpress-admin',
    admin_email='wp-admin@example.com',
    admin_password='anothertopsecret',
    site_title='My WordPress Blog',
    wordpress_plugins=[
        'akismet',
        'wordpress-seo',
        'wordfence',
    ],
)

result = lampsible.run()


# Joomla setup. This example is a little more complex,
# to showcase some more features. Webserver and
# database server are two different hosts,
# a database root password will be set.
# Certbot will run with the --test-cert flag,
# an older version of Joomla will be installed,
# some custom PHP extensions will be installed
# alongside the ones required by Joomla,
# and some extra environment variables will be set.
lampsible = Lampsible(
    web_user='someuser',
    web_host='somehost.example.com',
    # This assumes that you want your database server
    # to be reachable from the outside via the
    # domain dbserver.example.com, and within your
    # internal network, including your Joomla webserver,
    # via the private IP address 10.0.1.2.
    database_system_user='root',
    database_system_host='dbserver.example.com',
    database_host='10.0.1.2',
    action='joomla',
    email_for_ssl='someuser@example.com',
    ssl_test_cert=True,
    database_name='joomla',
    database_username='db-user',
    database_password='topsecret',
    database_root_password='supertopsecret',
    admin_username='your-joomla-admin',
    admin_email='joomla-admin@example.com',
    admin_password='anothertopsecret',
    # These extensions will be appended to the list of
    # extensions required by the system you are
    # installing (in this case Joomla).
    php_extensions=['php-curl', 'php-gd'],
    joomla_admin_full_name='Your Name',
    joomla_version='5.1.4',
    site_title='My Joomla Site',
    extra_env_vars={'FOO': 'bar', 'HELLO': 'world'}
)

result = lampsible.run()

```

## FAQ

* Why not just use Docker?

Lampsible is intended to be an homage to the old school: A simple and versatile LAMP stack.
If you want something similar with Docker, consider using [Docksible](https://github.com/belal-i/docksible),
another project that I maintain. It will install a web app onto your remote server with Docker Compose.
It also leverages Ansible locally under the hood.
