Pubblicare un'API Flask o FastAPI con dominio e HTTPS
Questa guida ti mostra come pubblicare un'API Flask o FastAPI su un server Python di OuiHeberg gestito in OuiPanel. Poi ti mostra come collegarla al tuo dominio in HTTPS con il Proxy Manager. Ti servono il codice della tua API (app.py, main.py…) e, se vuoi un indirizzo personalizzato, un nome di dominio.
Preparare i file dell'API
Scegliere tra Flask e FastAPI
| Criterio | Flask | FastAPI |
|---|---|---|
| Difficoltà | Principiante | Intermedio |
| Installazione | Semplice, senza compilazione | Più pesante, pydantic-core può dover essere compilato con Rust |
| Spazio su disco per l'installazione | Circa 100 MB | Fino a 5 GB se pydantic-core viene compilato |
| Prestazioni | Buone | Eccellenti (async) |
| Documentazione automatica | No (estensione) | Sì (Swagger, OpenAPI) |
| Validazione dei dati | Manuale | Automatica (Pydantic) |
| Ideale per | API semplici, server piccoli | API moderne, server grandi |
Il tuo server ha meno di 5 GB di storage? Scegli Flask.
Struttura dei file
La tua API deve avere questa struttura.
MonAPI/
├── app.py ← File principale (o main.py)
├── requirements.txt ← Dipendenze Python
├── .env ← Variabili d'ambiente (creato sul server)
└── routes/ ← (Opzionale) Cartella delle route
Opzione A: API con Flask
Ecco il file requirements.txt.
flask==2.3.3
python-dotenv==1.0.0
werkzeug==2.3.7
| Pacchetto | Ruolo |
|---|---|
flask | Framework web minimalista |
python-dotenv | Carica le variabili da .env |
werkzeug | Utility WSGI (incluse con Flask) |
Mantieni esattamente queste versioni per evitare problemi di compatibilità. Ecco il file principale, app.py.
import os
from dotenv import load_dotenv
# Caricare le variabili d'ambiente da .env
load_dotenv()
from flask import Flask, jsonify, request
# Creare l'applicazione Flask
app = Flask(__name__)
# ============================================
# ROUTE DELL'API
# ============================================
# Route principale
@app.route('/')
def home():
return jsonify({
'status': 'online',
'message': 'Benvenuto nella mia API Flask!',
'version': '1.0.0'
})
# Route di salute (health check)
@app.route('/health')
def health():
return jsonify({
'status': 'healthy',
'service': 'La mia API Flask'
})
# Esempio di dati (simulando un database)
items = [
{'id': 1, 'name': 'Item 1', 'price': 10.99},
{'id': 2, 'name': 'Item 2', 'price': 24.99},
{'id': 3, 'name': 'Item 3', 'price': 5.49}
]
# GET tutti gli elementi
@app.route('/api/items', methods=['GET'])
def get_items():
return jsonify({
'success': True,
'data': items,
'count': len(items)
})
# GET un elemento per ID
@app.route('/api/items/<int:item_id>', methods=['GET'])
def get_item(item_id):
for item in items:
if item['id'] == item_id:
return jsonify({
'success': True,
'data': item
})
return jsonify({
'success': False,
'error': 'Elemento non trovato'
}), 404
# POST creare un elemento
@app.route('/api/items', methods=['POST'])
def create_item():
data = request.get_json()
if not data or 'name' not in data:
return jsonify({
'success': False,
'error': 'Il campo "name" è obbligatorio'
}), 400
new_id = max(item['id'] for item in items) + 1 if items else 1
new_item = {
'id': new_id,
'name': data['name'],
'price': data.get('price', 0)
}
items.append(new_item)
return jsonify({
'success': True,
'message': 'Elemento creato con successo',
'data': new_item
}), 201
# PUT modificare un elemento
@app.route('/api/items/<int:item_id>', methods=['PUT'])
def update_item(item_id):
data = request.get_json()
for item in items:
if item['id'] == item_id:
item['name'] = data.get('name', item['name'])
item['price'] = data.get('price', item['price'])
return jsonify({
'success': True,
'message': 'Elemento modificato con successo',
'data': item
})
return jsonify({
'success': False,
'error': 'Elemento non trovato'
}), 404
# DELETE eliminare un elemento
@app.route('/api/items/<int:item_id>', methods=['DELETE'])
def delete_item(item_id):
for index, item in enumerate(items):
if item['id'] == item_id:
items.pop(index)
return jsonify({
'success': True,
'message': f'Elemento {item_id} eliminato con successo'
})
return jsonify({
'success': False,
'error': 'Elemento non trovato'
}), 404
# ============================================
# GESTIONE DEGLI ERRORI
# ============================================
@app.errorhandler(404)
def not_found(error):
return jsonify({
'success': False,
'error': 'Risorsa non trovata'
}), 404
@app.errorhandler(500)
def internal_error(error):
return jsonify({
'success': False,
'error': 'Errore interno del server'
}), 500
# ============================================
# AVVIO DEL SERVER
# ============================================
if __name__ == '__main__':
# Porta : utilizza SERVER_PORT (OuiPanel) o 5000 per impostazione predefinita
port = int(os.getenv('SERVER_PORT', 5000))
# IMPORTANTE : Ascoltare su 0.0.0.0 per OuiPanel
app.run(host='0.0.0.0', port=port)
L'API deve ascoltare su
0.0.0.0, e non sulocalhosto127.0.0.1, per essere raggiungibile dall'esterno.
Opzione B: API con FastAPI
FastAPI dipende da pydantic-core. Quando pip deve compilarlo, l'installazione richiede diversi GB di spazio su disco. In caso di errore
No space left on device, passa a Flask o aumenta lo storage del server.
Ecco il file requirements.txt.
fastapi==0.104.1
uvicorn==0.24.0
python-dotenv==1.0.0
| Pacchetto | Ruolo |
|---|---|
fastapi | Framework web moderno e veloce |
uvicorn | Server ASGI per FastAPI |
python-dotenv | Carica le variabili da .env |
Prevedi almeno 5 GB di storage libero per installare FastAPI. Ecco il file principale, app.py.
import os
from dotenv import load_dotenv
# Caricare le variabili d'ambiente da .env
load_dotenv()
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import Optional, List
# Creare l'applicazione FastAPI
app = FastAPI(
title="La mia API FastAPI",
description="Un'API REST moderna con FastAPI",
version="1.0.0",
docs_url="/docs", # Documentazione Swagger
redoc_url="/redoc" # Documentazione ReDoc
)
# ============================================
# MODELLI PYDANTIC (validazione dei dati)
# ============================================
class ItemCreate(BaseModel):
name: str
price: float = 0
description: Optional[str] = None
class Item(BaseModel):
id: int
name: str
price: float
description: Optional[str] = None
# ============================================
# DATI ESEMPIO (simulando un database)
# ============================================
items_db = [
{"id": 1, "name": "Item 1", "price": 10.99, "description": "Primo elemento"},
{"id": 2, "name": "Item 2", "price": 24.99, "description": "Secondo elemento"},
{"id": 3, "name": "Item 3", "price": 5.49, "description": "Terzo elemento"},
]
# ============================================
# ROUTE DELL'API
# ============================================
# Route principale
@app.get("/", tags=["Generale"])
async def home():
return {
"status": "online",
"message": "Benvenuto nella mia API FastAPI!",
"version": "1.0.0",
"docs": "/docs"
}
# Route di salute (health check)
@app.get("/health", tags=["Generale"])
async def health():
return {
"status": "healthy",
"service": "La mia API FastAPI"
}
# GET tutti gli elementi
@app.get("/api/items", tags=["Elementi"])
async def get_items():
return {
"success": True,
"data": items_db,
"count": len(items_db)
}
# GET un elemento per ID
@app.get("/api/items/{item_id}", tags=["Elementi"])
async def get_item(item_id: int):
for item in items_db:
if item["id"] == item_id:
return {"success": True, "data": item}
raise HTTPException(status_code=404, detail="Elemento non trovato")
# POST creare un elemento
@app.post("/api/items", status_code=201, tags=["Elementi"])
async def create_item(item: ItemCreate):
new_id = max(i["id"] for i in items_db) + 1 if items_db else 1
new_item = {
"id": new_id,
"name": item.name,
"price": item.price,
"description": item.description
}
items_db.append(new_item)
return {
"success": True,
"message": "Elemento creato con successo",
"data": new_item
}
# PUT modificare un elemento
@app.put("/api/items/{item_id}", tags=["Elementi"])
async def update_item(item_id: int, item: ItemCreate):
for index, existing_item in enumerate(items_db):
if existing_item["id"] == item_id:
updated_item = {
"id": item_id,
"name": item.name,
"price": item.price,
"description": item.description
}
items_db[index] = updated_item
return {
"success": True,
"message": "Elemento modificato con successo",
"data": updated_item
}
raise HTTPException(status_code=404, detail="Elemento non trovato")
# DELETE eliminare un elemento
@app.delete("/api/items/{item_id}", tags=["Elementi"])
async def delete_item(item_id: int):
for index, item in enumerate(items_db):
if item["id"] == item_id:
items_db.pop(index)
return {"success": True, "message": f"Elemento {item_id} eliminato"}
raise HTTPException(status_code=404, detail="Elemento non trovato")
# ============================================
# AVVIO DEL SERVER
# ============================================
if __name__ == "__main__":
import uvicorn
# Porta : utilizza SERVER_PORT (OuiPanel) o 8000 per impostazione predefinita
port = int(os.getenv('SERVER_PORT', 8000))
# IMPORTANTE : Ascoltare su 0.0.0.0 per OuiPanel
uvicorn.run(app, host="0.0.0.0", port=port)
FastAPI genera da solo una documentazione interattiva: Swagger UI su http://tuo-ip:porta/docs e ReDoc su http://tuo-ip:porta/redoc.
Caricare i file su OuiPanel
La Gestione file non ha un pulsante di caricamento. I file si inviano trascinandoli nella pagina.
Accedi a OuiPanel su dash.ouipanel.com e apri il tuo server Python.
Nel menu laterale, clicca su Gestione file.
Elimina i file predefiniti, se ce ne sono.
Dal tuo computer, trascina nella pagina
app.py,requirements.txte le tue cartelle (routes/,models/…).Quando compare il riquadro «Trascina i tuoi file qui», rilascia.
Ogni file inviato così è limitato a 100 MB.

Non caricare il tuo file
.env. Crealo direttamente sul server, è più sicuro.
Via SFTP
Per molti file, o file oltre i 100 MB, usa l'SFTP. Collegati con FileZilla, trascina tutto il contenuto della cartella dell'API, poi verifica che sia arrivato tutto. La guida Come connettersi in SFTP con FileZilla spiega la connessione.
Creare il file .env
Nella Gestione file, nella Radice, clicca su Crea un file.
Nella finestra «Crea un nuovo file», scrivi
.envin Nome del file, con il punto davanti, poi clicca su Crea il file.Clicca su
.envper aprirlo nell'editor, aggiungi le tue variabili, poi clicca su Salva.
# Configurazione dell'API
DEBUG=false
PORT=8000
# Database (se necessario)
DATABASE_URL=mysql://user:password@host:3306/database
# Chiavi API (esempi)
API_KEY=la_tua_chiave_api_segreta
SECRET_KEY=la_tua_chiave_segreta_per_jwt
Nessuno spazio intorno al
=.Nessuna virgoletta intorno ai valori semplici.
Non condividere mai questo file.

Scegliere il file di avvio e la versione di Python
OuiPanel deve sapere quale file Python avviare all'accensione. Su un server Python, questa impostazione è una variabile del server.
Apri Configurazione › Impostazioni del server.
Nella scheda Avvio del server, scegli la Versione sistema. L'elenco propone Python 2.7 e tutte le versioni dalla 3.7 alla 3.13, con la 3.13 in versione candidata. È consigliata la 3.12.
Nella scheda Variabili d'ambiente, scrivi il nome del tuo file in File Python di avvio (file di avvio; i nomi delle variabili sono in francese).
Clicca sulla spunta a destra del campo (Salva).
| Il tuo file principale | Valore di File Python di avvio |
|---|---|
app.py | app.py |
main.py | main.py |
api.py | api.py |
src/app.py | src/app.py |
Il campo File delle dipendenze della stessa scheda indica il file delle dipendenze da installare, requirements.txt di default.

Il nome deve corrispondere esattamente al tuo file, maiuscole comprese.
Avviare e provare l'API
Avviare il server
Nel menu laterale, clicca su Console, poi su Avvia. All'avvio il server installa i pacchetti di requirements.txt, poi esegue il tuo file.
Con Flask:
Installing requirements from requirements.txt...
Successfully installed flask-3.0.0 python-dotenv-1.0.0 gunicorn-21.2.0
Running app.py...
* Running on http://0.0.0.0:25639
Con FastAPI:
Installing requirements from requirements.txt...
Successfully installed fastapi-0.109.0 uvicorn-0.27.0 python-dotenv-1.0.0
Running app.py...
INFO: Uvicorn running on http://0.0.0.0:25639
Trovare l'indirizzo dell'API
Annota la porta mostrata nella console, per esempio
25639.Leggi l'indirizzo IP del tuo server in Vista Globale, alla riga Indirizzo principale.
L'indirizzo della tua API è
http://IP:PORTA, per esempiohttp://203.0.113.10:25639.
Provare gli endpoint
In un browser:
http://203.0.113.10:25639/mostra il JSON di benvenuto;http://203.0.113.10:25639/healthrisponde al controllo di stato;http://203.0.113.10:25639/docsapre la documentazione Swagger (FastAPI).
Con curl, ecco le chiamate di base.
# GET - Pagina principale
curl http://203.0.113.10:25639/
# GET - Lista degli elementi
curl http://203.0.113.10:25639/api/items
# GET - Un elemento specifico
curl http://203.0.113.10:25639/api/items/1
# POST - Creare un elemento
curl -X POST http://203.0.113.10:25639/api/items \
-H "Content-Type: application/json" \
-d '{"name": "Nuovo elemento", "price": 29.99}'
# PUT - Modificare un elemento
curl -X PUT http://203.0.113.10:25639/api/items/1 \
-H "Content-Type: application/json" \
-d '{"name": "Elemento modificato", "price": 39.99}'
# DELETE - Eliminare un elemento
curl -X DELETE http://203.0.113.10:25639/api/items/1
Con Postman o Insomnia, importa l'URL di base http://203.0.113.10:25639 e prova i tuoi endpoint.
Collegare un dominio con il Proxy Manager
Il Proxy Manager rende l'API raggiungibile a un indirizzo come https://api.miosito.com. Ti servono un dominio tuo e l'accesso alla sua zona DNS.
Creare il record DNS
Nel menu laterale, clicca su Proxy Manager.
La scheda La destinazione DNS di questo server indica l'indirizzo IP del proxy, come Valore.
Presso il tuo registrar (OVH, Cloudflare, ecc.), crea un record di tipo A per il sottodominio dell'API.
| Tipo | Nome | Valore |
|---|---|---|
A | api | L'indirizzo IP del proxy |

Su Cloudflare, lascia il proxy disattivato (icona grigia, DNS only). Altrimenti il certificato HTTPS non può essere emesso.
Collegare il dominio
Nel Proxy Manager, clicca su Aggiungi un dominio. Si apre il modulo Nuovo collegamento.
In Nome di dominio, scrivi
api.miosito.com.In Porta, scegli dall'elenco la porta su cui ascolta la tua API.
Lascia HTTPS su Certificato richiesto.
Clicca su Verifica il DNS. Quando il pannello mostra «Il DNS punta qui», clicca su Crea il reindirizzamento.

Il dominio compare in Domini collegati. La tua API risponde su https://api.miosito.com, con un certificato Let's Encrypt rinnovato automaticamente.
curl https://api.miosito.com/api/items
La guida Collegare un dominio al tuo server con il Proxy Manager descrive ogni passaggio e i messaggi di errore.
Collegare un database MySQL
Crea prima il database in OuiPanel, da Database › Crea un database. Il pulsante Informazioni ti dà poi host, nome utente e password. La guida Creare un database MySQL su OuiPanel descrive queste schermate.
Con Flask e PyMySQL, aggiungi questa riga a requirements.txt.
pymysql==1.1.0
Ecco un esempio di connessione.
import pymysql
import os
# Connessione a MySQL
connection = pymysql.connect(
host=os.getenv('DB_HOST', 'localhost'),
user=os.getenv('DB_USER', 'root'),
password=os.getenv('DB_PASSWORD', ''),
database=os.getenv('DB_NAME', 'mydb'),
charset='utf8mb4'
)
# Esempio di query
with connection.cursor() as cursor:
cursor.execute("SELECT * FROM items")
result = cursor.fetchall()
Aggiungi queste variabili al .env.
DB_HOST=mysql-host.ouiheberg.com
DB_USER=tuo_user
DB_PASSWORD=tuo_password
DB_NAME=tuo_database
Distribuire da un repository Git
Il tuo codice è su GitHub, GitLab, Bitbucket o Codeberg? La pagina Distribuzione scarica il repository e installa i pacchetti di requirements.txt al posto tuo, senza caricare i file a mano.
Nel menu laterale, clicca su Distribuzione.
Nel blocco Collegare un repository, compila Indirizzo del repository e Ramo.
In Accesso al repository, scegli Repository pubblico oppure una delle due opzioni per repository privati (chiave di distribuzione o token di accesso).
Spunta Distribuire a ogni push sul ramo se vuoi aggiornamenti automatici, poi clicca su Salva.
Clicca su Distribuisci ora.
Ogni distribuzione riavvia il server, che resta fermo mentre vengono installate le dipendenze. Se l'installazione non riesce, riparte la versione precedente. I file non tracciati da Git, come il tuo .env, restano al loro posto. Prima della prima distribuzione, il pannello fa un backup del server.

Per un repository privato è consigliata la chiave di distribuzione. Il pannello genera una chiave propria del server, da aggiungere al repository in sola lettura.
Risolvere un problema
L'API non si avvia
| Errore | Soluzione |
|---|---|
ModuleNotFoundError: No module named 'flask' | Controlla requirements.txt e riavvia. |
ModuleNotFoundError: No module named 'fastapi' | Controlla requirements.txt e riavvia. |
ModuleNotFoundError: No module named 'dotenv' | Aggiungi python-dotenv in requirements.txt. |
SyntaxError | Errore nel tuo codice Python. |
Errore «No space left on device» (FastAPI)
Si verifica quando pydantic-core, una dipendenza di FastAPI, deve essere compilato con Rust.
error: No space left on device (os error 28)
ERROR: Failed building wheel for pydantic-core
Usa Flask al suo posto, che non richiede compilazione.
Aumenta lo storage del tuo server (consigliati 5 GB o più).
Pulisci i file temporanei e riprova.
L'API si avvia ma non è raggiungibile
| Causa | Soluzione |
|---|---|
Ascolta su localhost | Passa a 0.0.0.0. |
| Porta sbagliata | Usa os.getenv('SERVER_PORT'). |
Controlla il tuo codice:
# ERRATO - ascolta solo in locale
app.run(host='localhost', port=5000)
app.run(host='127.0.0.1', port=5000)
# CORRETTO - ascolta su tutte le interfacce
app.run(host='0.0.0.0', port=port)
uvicorn.run(app, host='0.0.0.0', port=port)
Errore 502 Bad Gateway (Proxy Manager)
| Causa | Soluzione |
|---|---|
| API non avviata | Avvia il server in OuiPanel. |
| Porta sbagliata nel Proxy Manager | Controlla la porta del dominio collegato. |
| API andata in crash | Consulta la Console. |
Il file .env non viene letto
| Causa | Soluzione |
|---|---|
| python-dotenv mancante | Controlla requirements.txt. |
load_dotenv() non chiamato | Aggiungi load_dotenv() all'inizio del file. |
| Nome del file sbagliato | Il file deve chiamarsi esattamente .env. |
Errore CORS
Compare quando un frontend (React, Vue, ecc.) chiama la tua API da un altro dominio.
| Errore | Soluzione |
|---|---|
Access-Control-Allow-Origin | Aggiungi Flask-CORS o CORSMiddleware (vedi più in basso). |
Sicurezza e buone pratiche
Proteggere il file .env
| Da fare | Da evitare |
|---|---|
Creare il .env sul server | Caricare il .env dal tuo computer |
Aggiungere .env al .gitignore | Pubblicare il .env su GitHub |
| Passare i segreti tramite variabili | Scrivere le chiavi API nel codice |
Buone pratiche per un'API
Convalida sempre i dati inviati dagli utenti.
Servi l'API in HTTPS in produzione, con il Proxy Manager.
Non mostrare errori dettagliati in produzione.
Aggiungi un'autenticazione alle rotte sensibili.
Attivare CORS
Se un frontend ospitato su un altro dominio chiama la tua API, attiva CORS. Con Flask, aggiungi flask-cors.
# requirements.txt
flask-cors==4.0.0
from flask_cors import CORS
app = Flask(__name__)
CORS(app)
Con FastAPI, il middleware è già disponibile.
from fastapi.middleware.cors import CORSMiddleware
app.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_methods=["*"],
allow_headers=["*"],
)
Struttura avanzata
Per un'API più complessa, organizza il codice così. Questa struttura facilita la manutenzione delle API grandi.
LaMiaAPI/
├── app.py ← Punto di ingresso
├── requirements.txt
├── .env
├── routes/
│ ├── __init__.py
│ ├── items.py ← Rotte /api/items
│ └── users.py ← Rotte /api/users
├── models/
│ └── item.py ← Modello Item
└── utils/
└── helpers.py ← Funzioni utilitarie
Hai bisogno di aiuto?
Apri un ticket da Ticket › Aprire un ticket, oppure dal riquadro Contatta il supporto in fondo alla scheda del tuo server nell'area clienti. Puoi anche fare la tua domanda sul Discord di OuiHeberg.
Distribuisci le tue applicazioni Python con il nostro hosting ottimizzato e supporto dedicato.
Vedi le offerte →