Given that you are a seasoned web developer, it should not be difficult. And if you’re not, hey, are you sure you want to do this? :)

Setup La Distribution development environment

If you want to start hacking around La Distribution, we first recommend to setup a local copy from SVN and configure our command line utility. This what we’ll call from now “La Distribution development environment”.

First checkout La Distribution SVN repository:

Alternatively, you can also use our brand new Git repository:

Then update permissions:

As a web developer, I believe you know that working around user permissions and web server permissions can be a bit messy. In this tutorial, for the sake of simplicity and because we’re not working on real web server, we’ll fire chmod 777. If you know better, well, do it :)

Now, execute the web installer, say you’re on localhost:

Follow on screen instructions, create the first user, eventually register a MySQL database connection, and you’re done.

Now, we’ll make the ladis command line utility available from the terminal.

To do that, you can add La Distribution /bin/ directory to your PATH. Be careful, the following code is just an example, modify it to match your system. And, it’s an absolute path.

Type ladis in the terminal to check that it works. It should output something like that:

Create a web application using Limonade

Internally, we decided to write our first Micro Web Applications using the Limonade framework. If you want to find documentation on this framework, check their website.

You can start from our Hello World application, it will be a good basis. You can download it from our Github repository.

In this tutorial, we’ll grab it directly from the command line.

We’ll delete the .git folder because we just wanted to export this project, not actually track it. We’ll later version control again if needed.

Now, to make it your own, edit the dist/manifest.xml file and change the “id” and “name” of the application.

If you try http://localhost/ld-dev/my-application/ immediately it will not work. You have to register the application:

As seen before, in case you encounter permission issues. Fire:

Build the package, share it with the world!

We’ll now build the package to distribute our web application:

my-application.zip is now created.

To make it available to other users, you should push it to a public La Distribution repository. This repository should be hosted on a public server, accessible to others.

It’s easy, go on any public La Distribution installation under your control (ie: not localhost). Sign in, go in Settings, then Repositories. There, create a new local repository, name it “apps” for instance.

Click on Manage, and upload the .zip.

It’s online! Now you can pass your repository Public URL to your friends so that they can install your application.

Of course, you can also automatize the publication from the command line. In the web panel, copy the repository “Push URL”. Then register it locally:

Paste the Push URL, enter your credentials. And from now, pushing the package to the remote repository is that easy:

Conclusion

It was a bit technical but not that difficult, uh?

We’re now waiting for your apps!

Don’t hesitate to start simple apps, make it available to others and share them with a Git repository. People may be interested and help you bring your application to the next level. Speaking for me, I’m pretty sure I’ll do :)

In this tutorial we’re going to package Moonmoon a PHP based PlanetPlanet clone. It’s relatively simple, it’s representative of a typical web application, and better, it’s from my friend Maurice! Frankly, I had no clue if the packaging was possible before starting writing this tutorial, so let’s cross our fingers.

Create the simplest package.

For the first step, we’ll focus on the basics: the deployment procedure. We’ll let the user finishes the installation through the Moonmoon install form.

Let’s start.

1. Create an empty folder named ‘package’ containing 2 sub-folders: ‘application’ and ‘dist’.

2. In the dist folder, create a ‘manifest.xml’ file with the following content.

   <package>
     <id>moonmoon</id>
     <name>Moonmoon</name>
     <version>8.12-1</version>
     <type>application</type>
   </package>

3. In the ‘application’ folder, copy all the files of the application you want to package. You can download Moonmoon here.

   You should now have the following structure:

   

4. Now, zip everything in the ‘package’ directory (but not the ‘package’ directory itself). The ‘application’ and ‘dist’ directories must be at the root of the zip archive.

Test the package

5. Log in your La Distribution install, go in the Repositories panel and create a local repository if you don’t have already one.

6. Upload the zip archive you just created.



7. You should now be able to install a new instance of Moonmoon in the Applications panel.

Doh!

The cache directory was not created! I could have fixed that in the tutorial before but I chose to keep it real. It’s a common issue when trying to copy empty directories. One way to fix it is to create a dummy non empty file in the empty directories.

8. Now update your package version in the ‘manifest.xml’ file.

   <package>
     <id>moonmoon</id>
     <name>Moonmoon</name>
     <version>8.12-2</version>
     <type>application</type>
   </package>

9. Go on your Repository panel, upload the new version.

10. Go on the Application panel, update the application, it should works now!

Handling advanced installation

Because we want La Distribution to provide the same experience for all applications, we now have to skip Moonmoon install form.

There are generally three approaches to integrate an installation process with La Distribution:

1. Use the web installer provided by the application, and interact with it with PHP through HTTP. Isn’t that quirky ? Yes it is, but we don’t have often the choice, and well, you just have to say yourself it’s like using a REST API ;-)
2. Use the application libraries to perform the install. It’s currently rare but it’s the best approach, the La Distribution WordPress package has been developed this way for example.
3. Code directly in the package the installation procedure, by handling the necessary steps.

For Moonmoon, the install procedure is so simple that we’ll go with the third solution. Generally, it’s always easier to do the first, while the second is the one we have to promote, particularly for complex installs.

Introducing the installer

Basically, an installer is a PHP class that must be added in the ‘dist’ directory, named installer.php and extends the Ld_Installer class provided by La Distribution.

Now, let’s have a quick look at Moonmoon’s install.php file, line 9 to 25. It seems like we’ll just have to create two files. Let’s code that!

The install method will be automatically called when the user will create a new instance of the application with the La Distributions user interface.

Where does the preferences parameter come from?

The preferences come from the information entered by the user in La Distribution’s install form. By default, only the ‘title’ and ‘path’ preferences are present in this install form but you can add other preferences in the manifest file.

The ‘admin_password’ preference does not exist yet. So we’ll have to declare it in the manifest.

Don’t forget to increment the version number of the package. Packages are cached and you may become mad if you don’t do it!

Also, you can now delete the install.php file of the Moonmoon application as it is now useless.

Now, create the zip, upload it, test a new installation. Everything perfect!

Next?

In a next tutorial, we’ll see how to handle advanced users integration (SSO and Roles) and UI integration (integrating the permanent bottom bar).

As you can see, with a minimal technical background, creating La Distribution packages is fairly easy, now what are you waiting for to create your owns?

Thanks Benoît for reviewing this tutorial!