Skip to content

Backgrounds

How-to Guides

Technical References

VIP Local Development Environment /

Tips

Accessing WordPress

Newly created environments get a brand new empty database. This can be accessed via the PHPMyAdmin web url supplied by the start subcommand. You can use the import command to import data.

The super-admin credentials created for a new (empty) environment are vipgo/password.

Changes made to the database should be persisted until the environment is destroyed. That is, it should survive stopping the environment or the restart of the host machine.

Working with images & media

The local development environment does not have a files service replica, so all images are served locally. If data is imported and URLs search-replaced, these will likely 404 unless the corresponding media is placed in the container filesystem.

To address that we have introduced the concept of Media Redirect Domain. This domain can be set via --media-redirect-domain parameter to the create subcommand. If set, any requests returning 404 for a resource within uploads directory will be redirected to the media redirect domain – e.g. production site domain.

You can upload images via WordPress functionality, and those should be accessible. The uploads directory is also mapped to your host machine and can be found within a location of the environment.

vip dev-env info
NAME        example-site                                                                           
  LOCATION    /home/wpvip/.local/share/vip/dev-environment/example-site                               
  SERVICES    devtools, nginx, php, database, memcached, phpmyadmin, vip-search, statsd, wordpress 
  NGINX URLS  http://example-site.vipdev.lndo.site/                                                   
  STATUS      DOWN 
ls -al /home/wpvip/.local/share/vip/dev-environment/example-site
total 28
 drwxrwxr-x 5 wpvip wpvip 4096 aug 23 09:01 .
 drwxrwxr-x 7 wpvip wpvip 4096 aug 20 15:55 ..
 drwxrwxr-x 2 wpvip wpvip 4096 aug 23 09:10 config
 -rw-rw-r-- 1 wpvip wpvip 4449 aug 16 09:46 .lando.yml
 drwxr-xr-x 2 wpvip wpvip 4096 jun 18 09:04 log
 drwxr-xr-x 3 wpvip wpvip 4096 aug 16 09:48 uploads

Working on client code

The local development environment allows you to work on custom code (described here as client code, it is equivalent to the VIP Go repository code) locally on your machine, which makes the development feedback loop faster. Another advantage is that you have access to all the development tools you have in your environment. Finally, you have full access to all parts including the database.

For example:

# clone code locally if you don’t have it yet
git clone https://github.com/wpcomvip/my-environment.git ~/site-code

# pass the path to the code to the client-code component or provide the path when asked by the setup wizard. 
vip dev-env create --client-code="~/site-code" 

Stack services

The various services are running in containers, and some may expose ports on your machine. Accessible URLs will be reported when you run the start command (or in the output from info on running environment).

WordPress

The site is available through the URLs shown in the start output.

To log in to the site backend, use these credentials:

Username: vipgo
Password: password

WordPress core files are accessible in the environment location in wordpress folder. Modifications on these files will take immediate effect similar to the mapped mu-plugins or client code components. The changes will be local to only that specific environment but will be persisted.

To “revert” changes you can run vip dev-env destroy --soft, but note that this will remove all the volumes including your database state. Running vip dev-env start afterwards will result in a fresh new environment.

Database

The MySQL (MariaDB) database can be accessed via the exposed port shown in the info table at the end of start . If you chose to enable PHPMyAdmin web interface, the URL will be also listed there.

Logs

PHP error logs are going to be available in Query Monitor in the browser, but raw logs can be tailed from the directory where the site configuration is stored.

Each slug or environment name has a separate subdirectory in ~/.local/share/vip/dev-environment containing a config and log directory and a .lando.yml YAML file.

To tail the PHP logs for the environment named example-site:

tail -f ~/.local/share/vip/dev-environment/example-site/log/debug.log

Object cache

The same object cache used in production is running in the local development environment. You may notice that some database queries are automatically cached and do not show up in Query Monitor. This is normal!

To clear the object cache (add a --url argument as needed, the cache for subsites in a multisite must be flushed individually):

wp cache flush

The Elasticsearch service that supports Enterprise Search is running locally as well, so you can test all aspects of search, including indexing.

Troubleshooting Dev Environment

Here are some places to look for extra logs if dev-env is not being created or starting as expected.

Set Environment Variable DEBUG

You can set environment variable DEBUG with the following keys to print more information on the console:

  • @automattic/vip:bin:dev-environment – shows most of vip CLI debuging lines
  • @automattic/vip:bin:dev-environment-lando – shows lando internal debugging lines

The setting environment differs per operating system.

pavel>~ $ export DEBUG="@automattic/vip:bin:dev-environment"
pavel>~ $ vip dev-env info
  @automattic/vip:bin:dev-environment Args:  [] Options:  {} +0ms
  @automattic/vip:bin:dev-environment Will get info for an environment vip-local +0ms
  @automattic/vip:bin:dev-environment Instance path for vip-local is: /home/user/.local/share/vip/dev-environment/vip-local +0ms
	  
...

Docker logs

Local VIP Development Environment is composed of several docker containers. Although it might be difficult to guess which is causing an issue, it might be useful to check individual container logs. Especially php-fpm and traefik containers can provide useful insights.

docker ps will show all the running containers including their names. The name can then be used in docker logs <name> to show the logs.

 $ docker ps
CONTAINER ID   IMAGE                                                 COMMAND                  CREATED          STATUS          PORTS                                                                     NAMES
0a368d39d5fd   phpmyadmin/phpmyadmin:5.1.1                           "/lando-entrypoint.s…"   27 seconds ago   Up 25 seconds   127.0.0.1:49161->80/tcp                                                   vipdevviplocal_phpmyadmin_1
14161140202c   bitnami/elasticsearch:7.8.0                           "/lando-entrypoint.s…"   27 seconds ago   Up 25 seconds   9300/tcp, 127.0.0.1:49160->9200/tcp                                       vipdevviplocal_vip-search_1
9c66c331852e   wpvipdev/dev-tools:0.4                                "/lando-entrypoint.s…"   27 seconds ago   Up 25 seconds                                                                             vipdevviplocal_devtools_1
33e29bc0f254   ghcr.io/automattic/vip-container-images/php-fpm:7.4   "/lando-entrypoint.s…"   27 seconds ago   Up 25 seconds   9000/tcp                                                                  vipdevviplocal_php_1
7188c947dc69   bitnami/memcached:1.5.12                              "/lando-entrypoint.s…"   27 seconds ago   Up 25 seconds   11211/tcp                                                                 vipdevviplocal_memcached_1
245aece0559a   bitnami/mariadb:10.3.27-debian-10-r84                 "/lando-entrypoint.s…"   27 seconds ago   Up 25 seconds   3306/tcp                                                                  vipdevviplocal_database_1
16fb0bfbed92   wpvipdev/nginx:1.19.2-2                               "/lando-entrypoint.s…"   27 seconds ago   Up 25 seconds   80/tcp                                                                    vipdevviplocal_nginx_1
16c6c4461260   wpvipdev/wordpress:5.7.2                              "/lando-entrypoint.s…"   27 seconds ago   Up 25 seconds                                                                             vipdevviplocal_wordpress_1
41479827e749   traefik:2.2.0                                         "/lando-entrypoint.s…"   28 seconds ago   Up 27 seconds   127.0.0.1:80->80/tcp, 127.0.0.1:443->443/tcp, 127.0.0.1:49159->8080/tcp   vip-dev-env-proxy_proxy_1


$  docker logs vipdevviplocal_php_1
<logs here>

Last updated: November 16, 2021