Install & Setup

Atlantis From Scratch

System Overview


Most of these are not hard requirements. Deviations will require adjustments be made to work with whatever you prefer to use instead. The project itself and all documentation is written expecting an environment that smells simliar to this. This is due to how Linux distros tend to compile their own opinions into things, such as where services should look for config files.

Ubuntu (20+)
  • This distro tends to stay current enough with PHP these days. The most important thing was it has packages for all the modules needed.
Apache 2.4
  • Ubuntu symlinks Apache configs into /etc/apache2/sites-enabled.
PHP 8.1+
  • Required Modules: cli, common, curl, imagick, mbstring, memcache, mysql, opcache, xml, zip.
  • Ubuntu compiles almost all PHP features as separate packages. This is where you will see the most variation between Linux distros. Some will compile everything into fewer larger packages, some compile it all into many small packages.
  • Ubuntu stores PHP configurations in /etc/php/<major>.<minor>/apache2. They contain a php.ini file and conf.d directory you can drop additional ini files into.
MariaDB or MySQL 5.x (optional)
  • Database is completely optional if you need one or not.
Tips:
Add ./vendor/bin to your PATH to gain easy access to vendor scripts $ project.atl, $ dev.atl, etc, without typing the full path to it. All examples will be making use of this.
The .atl commands have help to see more info. Example: $ project.atl help db will show all the possible db command arguments.

Installation and Setup


This project is under active development and is still depending on rolling source repository checkouts. The following composer.json settings are required to install and update. They will be set automatically via the project bootstrapping.

"minimum-stability: "dev",
"prefer-stable": true

Bootstrap Project Directory

This will fetch some basic structure including a pre-configured composer.json.

$ git clone https://github.com/netherphp/project app
$ cd app
$ rm -rf .git

Install Framework

Download the framework and dependencies.

$ composer require netherphp/atlantis dev-master

Set everything up. This will bootstrap a bare bones project to build upon in the project directory.

$ project.atl init -y

Update the autoloader, grabbing any last second updates along the way.

$ composer update

Edit Config

The primary configuration is found in the conf/config.php file. Update the ConfProjectID, ConfProjectName, and ConfProjectDomain as a minimum. Additionally there are environment specific config config/env/dev/config.php for settings that may need to be specific to your local environment, for example a test domain or API keys.
To make a new configuration environment, for example a prod environment, copy the dev environment and make any required changes. $ cp -r conf/env/dev conf/env/prod
To set the current environment name, for example to prod: $ echo "prod" > env.lock

Run Demo

At this point PHP's built-in web server should be able to serve the application over basic HTTP. That can be tested with the following command:

$ php -S localhost:8080 -t www

Use Simple Parking Page

The framework comes with a theme called soon that will display a simple coming soon page to quickly park a project. Within conf/config.php set Surface\Library::ConfThemes to [ 'local', 'soon', 'default' ]. The Themes work together as a stack. If you want to customise the parking page the version in soon can be copied into local, edited, and it will be loaded instead due to the order of the themes set. Here is an example of adding that line after the Avenue configuration settings.

($Config)
->Set(Atlantis\Key::ConfLibraries, [ ])
->Set(Avenue\Library::ConfRouteFile, $App->FromProjectRoot('routes.phson'))
->Set(Avenue\Library::ConfRouteRoot, $App->FromProjectRoot('routes'))
->Set(Surface\Library::ConfThemes, [ 'local', 'soon', 'default' ]);

Database Configuration


Configure the Default connection.
$ project.atl db --set --host=localhost --db=dbname --user=dbuser --pass=dbpass

Web Server (Apache2)


Configure Web Server (Apache)
If this is the initial setup, it will be easier to say no to SSL to start with.
$ web.atl config
$ web.atl setup
$ web.atl reload
At this point the real web server should be able to serve the application over basic HTTP.

SSL Certificates from acme.sh


Install acme.sh

There is an opinionated install script to get acme.sh installed.

$ sh vendor/netherphp/atlantis/tools/acmesh-install-linux.sh email@for-ssl.notifications
  • Installs to /opt/acmesh.
  • Confs located at /opt/acmesh/local/confs.
  • Certs located at /opt/acmesh/local/certs.
  • The email address provided to the installer script will be sent to your SSL provider, which they will use to warn you about expiry issues.

Issue SSL Certificate (via Magic DNS API)

A list of the DNS hosts supported by acme.sh via DNS API and how to configure them can be found here. Atlantis comes with DNS scripts for DigitalOcean and Porkbun. Copy the ones you need out and edit them to fill in the required information for that host.

  • $ cp vendor/netherphp/atlantis/templates/acmesh-issue-docean.txt bin/ssl.sh
  • $ cp vendor/netherphp/atlantis/templates/acmesh-issue-porkbun.txt bin/ssl.sh

Any SSL issue done in this method will only ever actually be used once. After the initial issue acme.sh will track what is needed to perform future renewals. It is however advisable to keep your issue script laying around in the event you need to expand upon it, such as adding alternate domains your project might want to answer for.

Other modes of fetching certs with acme.sh can be found here.


Renew SSL Certificate

acme.sh should have automatically added a cron job for handling renewals. This can be checked with $ crontab -l. It should look simliar to this:

20 4 * * * "/opt/acmesh"/acme.sh --cron --home "/opt/acmesh" --config-home "/opt/acmesh/local/confs" > /dev/null

The cron can be reinstalled with $ acme.sh --install-cronjob.