While developing LuCI web services, I found this is quite annoying for moving codes back and forth from my machine to the router.

So, I decided to setup a LuCI development environment on my own machine. Below are steps for doing so.

Prerequisites

Ubuntu 12.04

OS I have tested

LuCI

If you havn’t installed, please refer to my another blog post

Apache2 (Version: 2.2.22-1ubuntu1)

Version of Apache2 is not important if you can take care the PATH issues. For example, the HTML root directory.

Command to install apache2


apt-get install apache2

How it work

Below is a simplified diagram. I have not drawn all the components involved.


           CGI

|APACHE| <-----> |         LuCI           |

# Inside LuCI

|cgi-bin/luci| <--> |luci.sgi.cgi| <--> |luci core|

According to above diagram, we only need to setup a CGI script for briding up apache and luci

Steps

1. Checkout cgi directory location

We need to put luci (a cgi script) in there such that Apache can run.


$> cat /etc/apache2/sites-enabled/000-default

...

ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/

...

ScriptAlias means apaches will run a corresponding script in /usr/lib/cgi-bin when there are requests to URL http://HOST/cgi-bin/ANY_CGI_SCRIPT

Therefore, we should put luci in /usr/lib/cgi-bin

2. Get a LuCI repository

I am using version LuCI.0.12 from the github here

3. Get luci from the luci repository

Define <LUCI> to be the path for luci repository


# Get CGI script

$> sudo cp <LUCI>/host/www/cgi-bin/luci /usr/lib/cgi-bin/

# Get CSS html template etc

$> sudo cp -r <LUCI>/host/www/luci-static /var/www

# Change permission

$> sudo chown -R www-data:www-data /var/www/luci-static

$> sudo chmod 755 /usr/lib/cgi-bin/luci

4. Edit Apache configuration /etc/apache2/sites-enabled/000-default

Make sure you have been replaced LUA_PATH, LUA_CPATH, LUCI_SYSROOT and LD_LIBRARY_PATH with your own path.


....

<Directory "/usr/lib/cgi-bin">

        SetEnvIf \

                Request_URI ".*luci.*" \

                LUA_PATH=/home/mondwan/Documents/git/luci/host//usr/lib/lua/?.lua;/home/mondwan/Documents/git/luci/host//usr/lib/lua/?/init.lua;$LUA_PATH; \

                LUA_CPATH=/home/mondwan/Documents/git/luci/host//usr/lib/lua/?.so;$LUA_CPATH; \

                LUCI_SYSROOT=/home/mondwan/Documents/git/luci/host \

                LD_LIBRARY_PATH=/home/mondwan/Documents/git/luci/host/usr/lib:

        AllowOverride None

        Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch

        Order allow,deny

        Allow from all

</Directory>

....

5. Restart apache


$> sudo service apache2 restart

6. Create a directory for LuCI

The directory /etc/config simulates a config system in OpenWRT which LuCI relies on.


$> mkdir -p /etc/config

7. Write following default contents into /etc/config/luci


config core 'main'

    option lang 'auto'

    option mediaurlbase '/luci-static/openwrt.org'

    option resourcebase '/luci-static/resources'

config extern 'flash_keep'

    option uci '/etc/config/'

    option dropbear '/etc/dropbear/'

    option openvpn '/etc/openvpn/'

    option passwd '/etc/passwd'

    option opkg '/etc/opkg.conf'

    option firewall '/etc/firewall.user'

    option uploads '/lib/uci/upload/'

config internal 'languages'

    option en 'English'

config internal 'sauth'

    option sessionpath '/tmp/luci-sessions'

    option sessiontime '3600'

config internal 'ccache'

    option enable '1'

config internal 'themes'

    option Bootstrap '/luci-static/bootstrap'

8. View on browser

Errors are expected :)

Ubuntu and Openwrt are 2 different OS. They build up with different set of commands for managing computational resources.

In other words, most of the application from official repository cannot be reused here unless you have ported all the internal details from Openwrt to Ubuntu.

NOTE: Some of them have been port to Ubuntu in this PPA

9. Remove incompatitable components so that we can run admin interface


$> cd <LUCI>/host/usr/lib/lua/luci/controller

$> mv admin/ ..

$> rm -fr *

$> mv ../admin/ .

# Clean up cache

$> sudo rm -fr /tmp/luci-indexcache /tmp/luci-modulecache/

10. Try again

If you can see above picture, you can start developing your own LuCI application under folder <LUCI>/host/usr/lib/lua/luci/controller

NOTES

ADMIN interface will not work as expected

As stated above, most commands from openwrt are not ported to Ubuntu (eg: ubus). The admin interface will not work as expected.

Missing folders I mentioned above

Make sure you are using luci-0.12 since the latest luci alters the build process somehow.

If you are using GIT for downloading source codes, here are commands for checking out luci-0.12


$> cd PROJECT_ROOT

$> git checkout luci-0.12

Then follow my blog post for installation

Apache CGI does not work as expected

Please take a look here and make sure cgi module has been enabled.

Unable to run /cgi-bin/luci due to permission problem

Try to replace these lines


Order allow,deny

Allow from all

to this


Require all granted

Extras

Disable cache mechanism by comment 2 lines

By default, LuCI caches Lua files as binaries. Modification in your applications will be ignored if binaries had been created. Here is a way for disabling such mechanism.


$> vi /usr/lib/cgi-bin/luci

-- require "luci.cacheloader"

require "luci.sgi.cgi"

-- luci.dispatcher.indexcache = "/tmp/luci-indexcache"

luci.sgi.cgi.run()

References

Updates

2015/6/26
- Update notes contents about missing folder
2017/3/5
- Fix a typo in the script
- Add a link about enable Apache CGI
- Add how to fix permission problems from Apache (Thanks +Anton Key )
- Rewrite certain sentances and unify the style
2020/01/05
- Add a note on ubutnu PPA (from stokito)

Stuff Corner

2015/06/03

How to setup LuCI web framework with Apache on Ubuntu 12.04