Add media to a VIP Local Development Environment

Media files can be uploaded, imported, or proxied to a running VIP Local Development Environment. It is recommended to import media files after a VIP Local Development Environment is confirmed to be up and running and has been configured to run with locally cloned application code.

A local uploads directory is mapped to a local environment’s LOCATION URL where media files can be stored.

To locate a local environment’s uploads directory, retrieve the LOCATION URL of the local environment with vip dev-env info. For example:

$ vip dev-env info --slug=example-site
  SLUG        example-site                                                                           
  LOCATION    /home/example-user/.local/share/vip/dev-environment/example-site                               
  SERVICES    devtools, nginx, php, database, memcached, phpmyadmin, elasticsearch, wordpress 
  NGINX URLS  http://example-site.vipdev.lndo.site/                                                   
  STATUS      DOWN 

Based on the output of the above command example, the uploads directory can be found at:
/home/example-user/.local/share/vip/dev-environment/example-site/uploads/

Limitations

The VIP Local Development Environment does not currently include a replica of the VIP File System. When developing features for an application that rely on the VIP File System service, it is strongly recommended to stage changes and perform tests on a non-production VIP Platform environment instead of the VIP Local Development Environment.

Upload media files

Media files can be uploaded with the WordPress media uploader in post content or in the Media Library. Uploaded files will be stored in the local uploads directory that is mapped to a local environment’s LOCATION URL.

Import media files with VIP-CLI

After importing a VIP Platform environment’s database to the local environment, media files may not appear as expected on the front end of the local site or in the WordPress Media Library. To remedy this, media files must be imported to the local site’s uploads/ directory and media file URLs in the database must map correctly to that local directory.

1. Download a Media Backup for a VIP Platform environment from the VIP Dashboard.
2. Decompress the downloaded  *.zip file.
3. Import the /uploads/ directory, located in the decompressed file structure: /wp-content/uploads/ using the VIP-CLI command vip dev-env import media <path-to-uploads-directory>.

In this command example, the contents of /Users/example-user/Desktop/wp-content/uploads will be imported to the uploads/ directory that is mapped to the LOCATION URL of a local environment with an assigned --slug value example-site:

vip dev-env import media --slug=example-site /Users/example-user/Desktop/wp-content/uploads

If the media files do not load as expected after completing the above steps, a search and replace operation may need to be performed on the database. Use exec to execute WP-CLI commands such as search-replace against the local environment’s database. The search-replace operations should update media file URLs in the database to point to the location of the imported media files in the local uploads directory.

For example, if a user imported a database backup and a media backup of their production site example-site.com into their VIP Local Development Environment, the media file URLs in the local environment’s database should be updated by searching for the string example-site.com/wp-content/uploads and replacing it with example-site.vipdev.lndo.site/wp-content/uploads:

vip dev-env exec --slug=example-site -- wp search-replace example-site.com/wp-content/uploads example-site.vipdev.lndo.site/wp-content/uploads --all-tables --dry-run

Proxy media files

After importing a VIP Platform environment’s SQL database to the local environment, media file requests can be proxied to the VIP Platform environment where the database originated. This eliminates the need to download and import media files to a local machine.

To enable media URLs in the local database to proxy to the VIP Platform environment, set the --media-redirect-domain option to the VIP Platform environment’s primary domain.

The --media-redirect-domain option can be set when creating a VIP Local Development Environment, or with the update subcommand for an existing local environment.

In this command example, a local environment is created with the assigned --slug value example-site, and --media-redirect-domain is configured to proxy media requests to the VIP Platform production site with the primary domain www.example.com:

vip dev-env create --slug=example-site --media-redirect-domain=www.example.com

Requests for a media file will first refer to the local uploads directory that is mapped to a local environment’s LOCATION URL. If the requested media file is not found there, a 404 is returned. The request is then redirected to the uploads directory of the domain that was assigned to the --media-redirect-domain option.

To work as expected

• A search-replace operation must have been completed on the database to replace VIP Platform environment domain values (e.g. example-site.com) with local domain values (e.g. example-site.vipdev.lndo.site).
• Local domain values must have a subdomain structure (e.g. sub.example-site.vipdev.lndo.site) and not a subdirectory structure (e.g. example-site.vipdev.lndo.site/sub).