What to Include in Environment Deployment Delivery Docs: A Template to Avoid Handover Disputes

Delivering only an “accessible website” after deployment will inevitably lead to disputes later on: not knowing where to find config files, not knowing the commands to restart services, and not knowing who to contact when issues arise. These are not technical problems; they are a result of missing documentation.

The standard for a qualified delivery document is: a person unfamiliar with the project should be able to independently perform daily operations and conduct initial fault diagnosis using it.

What the Document Should Contain

Template

# Project Deployment Delivery Document

## 1. Environment Information
- OS: Distribution and version
- Web: Nginx/Apache and version
- PHP: Version + list of key extensions
- Database: Version, database name(s)
- Others: Redis, Node.js, etc.

## 2. Directory Structure
- Site Root: /var/www/html
- Logs: /var/log/nginx/ /var/log/php-fpm/
- Backups: /data/backup/ (synced off-site to backup server)
- Upload Dir: /var/www/html/wp-content/uploads

## 3. Services & Ports
| Service | Port | Description |
|---|---|---|
| Nginx | 80/443 | Public facing |
| php-fpm | 9000 | Localhost only |
| MySQL | 3306 | Internal network only, not public |

## 4. Configuration Files
- Site Config: /etc/nginx/conf.d/example.conf
- PHP Config: /etc/php.ini, /etc/php-fpm.d/www.conf
- DB Config: /etc/my.cnf
- App Config: /var/www/html/wp-config.php
- How to Apply Changes: nginx -t && nginx -s reload

## 5. Common Operations
- Restart Web: systemctl restart nginx
- Restart PHP: systemctl restart php-fpm
- Restart DB: systemctl restart mysqld
- View Logs: tail -f /var/log/nginx/error.log

## 6. Accounts & Credentials
- Delivery Method: Encrypted channel
- List: SSH, Database, App Admin, Third-party services
- Rotation Required After Delivery: Yes

## 7. Backup & Recovery
- Backup Content: Website files, database, configs
- Backup Location: Local + Off-site
- Frequency & Retention: Daily, keep for 30 days
- Recovery Method: See appendix steps
- Last Recovery Drill Date: ____

## 8. Known Issues & Notes
- Unresolved Issues: ____
- Special Configs & Reasons: ____ (to prevent accidental modification)

## 9. Change Log
| Date | Change Description | Operator |
|---|---|---|

The Three Most Often Missing Items

① Reasons for Special Configurations

Example:
- A specific location block in nginx has a special rule
  Reason: An early feature dependency; removing it breaks XX functionality.
- A cron job is set to run at 3 AM daily
  Reason: To avoid business peak hours and backup windows.

Configs without stated reasons will likely be “optimized” away by successors, triggering issues that were already resolved.

② Recovery Methods (Not Just Backup Methods)

Many documents state “automatic daily backups” but fail to explain how to restore. When a real restoration is needed, you have to look it up then, which is usually during an emergency.

Recovery Steps (specific enough to execute directly):
1. Locate backup file: ls /data/backup/[date]/
2. Restore database: mysql dbname < db.sql
3. Restore files: tar -xzf www.tar.gz -C /var/www/html
4. Fix ownership: chown -R www:www /var/www/html
5. Verify: curl -I https://example.com/

③ Date of Last Recovery Drill

The existence of this item serves as a reminder: a backup that hasn’t been tested is not a backup.

Where to Store the Document

The key is “updatable” and “findable.” Documents sent via chat often become obsolete within three months—not because the content is wrong, but because no one updates them anymore.

Decision Tree

Writing Delivery Docs
├─ Standard: Someone unfamiliar can operate independently
├─ Mandatory
│  ├─ Environment & Versions
│  ├─ Directories & Config Locations
│  ├─ Services & Ports
│  └─ Start/Stop Commands
├─ Most Often Missed (But Most Valuable)
│  ├─ Reasons for Special Configs ← Prevents accidental changes
│  ├─ Recovery Steps ← Avoids frantic searching during emergencies
│  └─ Known Issues
└─ Maintenance
   ├─ Store in a collaborative/updatable location
   └─ Update Change Log with every change

Scenario Simulation: Successor Deletes a “Redundant” Config, Causing Downtime

Symptom: An environment is handed over to a new team. While organizing, a new colleague finds a configuration item that appears unused, deems it legacy debris, and removes it. Subsequently, a periodic business process starts failing.

1. Investigate what the config actually serves → Tracing reveals it corresponds to a scheduled task that only activates during specific time windows, making it invisible during normal operation.
2. Understand why it wasn’t documented → The handover doc listed the config value but omitted “why this value” and “what happens if changed.”
3. Restore the config to resume business → Prioritize止血 (stopping the bleeding); resolve disputes later.
4. Audit for similar items → Inventory other configs using the same standard to find others lacking reason explanations, rather than just fixing this one.
5. Rewrite docs using the “Three Elements” format → Every config item must include Value, Reason, and Impact of Change.
6. Establish a Rule → Do not touch configs whose purpose is unclear; verify first. Guesswork-based cleanup is prohibited.

# Exporting "actually effective configs" at handover is more reliable than handwritten lists
crontab -l -u root
ls -la /etc/cron.d/
systemctl list-unit-files --type=service | grep enabled
nginx -T > nginx-effective.conf 2>/dev/null
ss -lntp

# Check which tasks depend on a specific service (to avoid misjudging purpose)
grep -rIl 'ServiceName|ConfigKeyword' /etc/cron.d/ /etc/systemd/system/ 2>/dev/null | head

# After recovery, confirm the scheduled task still runs
systemctl list-timers --all | grep TaskName

Root Cause: The handover doc only recorded “what the config is,” missing “why” and “what happens if changed.” The successor had to guess, and guesses naturally lean toward “delete what looks useless.”

Two Key Takeaways:

• Every config in the handover doc must include three elements: Value, Reason, and Impact of Change. Without the latter two, the doc is just a list and offers no protection.
• Export “actually effective configs” via commands instead of relying on memory. The former reflects the current true state; discrepancies between the two are exactly where documentation needs improvement.

Consequence Comparison for the Three Most Missing Items

Among these four, “Why configured this way” has the lowest remediation cost and highest return. A seemingly redundant config often exists to bypass a specific issue. Without stating the reason, a successor deletes it thinking it’s useless, immediately reproducing the problem. Since the context is unknown, troubleshooting starts from scratch.

The Three Elements Each Config Line Should Carry

1. What is the Value: Specific config item and its value.
2. Why this Value: What problem it solves or what limitation it bypasses.
3. What Happens if Changed: Which scenarios are affected and how to verify.

Listing only #1 is a config inventory; adding #2 and #3 makes it a handover-ready document. The difference: the former lets the successor follow instructions; the latter tells them what not to mess with.

# Export actual effective configs before delivery (more reliable than handwritten lists)
nginx -T > nginx-effective.conf 2>/dev/null
php --ini
systemctl list-unit-files --type=service | grep enabled
crontab -l -u root
ss -lntp

Actual configs exported via commands are more trustworthy than memory-based lists: they reflect the true state currently in effect, not “what it should be.” Discrepancies between the two are often where documentation gaps exist.

8 Common Pitfalls

1. Documenting backups but not recovery: Searching for recovery steps only during emergencies.
2. Omitting config reasons: Leading to accidental modifications by successors.
3. Sending docs via chat: Hard to find and prone to expiration.
4. Omitting known issues: Successors repeat past mistakes.
5. Failing to update after changes: Docs become inaccurate quickly.
6. Storing plaintext passwords in docs: Should be delivered separately via encrypted channels.
7. Omitting ports and exposure surface: Makes security audits difficult.
8. No change log: Impossible to correlate recent changes when issues arise.

Real Customer Feedback (From Cloud Marketplace Reviews & Inquiries for Similar Products)

The following excerpts are taken from real buyer reviews and inquiries for similar O&M services on Alibaba Cloud / Tencent Cloud / Huawei Cloud Marketplaces (providers include our store and peers, provided solely for reference of genuine feedback, not fictional tickets):

1****n Rating: 5.0 Jan 04, 2018 18:04

d****9 Rating: 5.0 Feb 15, 2023 09:11 a****7 Rating: 5.0 Feb 15, 2023 09:10 d****8 Rating: 5.0 Feb 14, 2023 10:48 d****8 Rating: 5.0 Feb 14, 2023 10:43 a****3 Rating: 5.0 Jan 17, 2023 17:20

9****3 Rating: 5.0 Jul 22, 2021 10:31