Running OXID eShop in a subdirectory

Blog Posts über OXID
1

I’ve been asked several times how to run OXID eShop in a subdirectory like . Actually, there are several methods to achieve this goal including the adaption of your apache vhost or via .htaccess forwarding. In this blog post I will describe how to use unix symlinks to resolve the situation as it is a very smart solution that can even be used to roll out and back between several versions of your project without any downtime.

We strongly advise to use a local development environment for running your OXID eShop project. Most likely, at some point, you want to transfer it to your production machine and will have a file structure like that on your server:

/var/www/. #doc root, depending on the system you use
├── composer.json
├── composer.lock
├── source
└── vendor

Theoretically, if your domain points to the web root (e.g. /var/www/), the shop can be run at the URL – which is definitely ugly: I mean, what should “source” mean to the visitor of your shop? Very often, web hosting providers have the possibility to let the domain point to the subdirectory so you can easily let your OXID eShop project run on .

Hint: please don’t try to rename the source/ folder. You’ll definitely fail

Here’s a very smart solution if you have no clue how to adapt your apache vhost: simply connect to your server via SSH, move to the root directory (see above) and set a unix symlink using this command:

ln -s source/ shop

ln is the command to set a link, -s is an option to define it as a symbolic instead of a hard link. source/ is your target directory and shop is the link name.

Now you have to adapt the values for sShopURL, sShopDir and sCompileDir in the file source/config.inc.php: simply point them to shop/ instead of source/.

Don’t forget to alter the rewrite base value in source/.htaccess as well.

Last step: clean up your source/tmp/ directory before you fire up your browser at and check if all alterations were successfully proceeded.

Downtimeless deployment with subdirectories

With the same method it is possible to switch back and forth between different project versions – practically without any downtime, with project folder names that could be ugly as sin, and your clients will not even notice them. I’ll show you:

/var/www/. #doc root, depending on the system you use
├── my_oxid_eshop_project_v1.0
│   ├── composer.json
│   ├── composer.lock
│   ├── source
│   └── vendor
├── my_oxid_eshop_project_v1.1
│   ├── composer.json
│   ├── composer.lock
│   ├── source
│   └── vendor
├── my_oxid_eshop_project_v1.2
│   ├── composer.json
│   ├── composer.lock
│   ├── source
│   └── vendor
├── my_oxid_eshop_project_v1.3
│   ├── composer.json
│   ├── composer.lock
│   ├── source
│   └── vendor
├── my_oxid_eshop_project_v2.0
│   ├── composer.json
│   ├── composer.lock
│   ├── source
│   └── vendor
└── my_oxid_eshop_project_v2.1
    ├── composer.json
    ├── composer.lock
    ├── source
    └── vendor

Let’s say you did in fact develop on your local machine and uploaded these project states to your production server. All these versions might be connected to the same database. You just check the new state in your browser if it works for you. If so, switch to it inside the doc root using the symlink function again:

ln -sfn my_oxid_eshop_project_v2.1/source/ shop

Hey, there’s a customer complaining about a bug you accidentally added with your new version – just swiftly roll back:

ln -sfn my_oxid_eshop_project_v2.0/source/ shop

I think you got the idea, didn’t you? If you have any questions, please don’t hesitate to post them in the linked forum thread below

Many thanks to Joscha Krug for sharing this knowledge and the inspiration for this blog post!

3 Likes